Notion Design Context

Notion Design Context

The codebase says what the system does. It rarely says why anyone wanted it to.

This skill closes that gap from the team's own documents — on demand, and always subordinate to the code. Notion tells you intent. Only source tells you behaviour. When the two disagree, that disagreement is usually the most valuable thing in the answer.

Four hard rules. Everything else is judgement:

1. Read the code first, and say what it settled.
2. Ask before searching, every time.
3. The sub-agent does the fetching — never the main thread.
4. Every claim from a document carries a link.

The rest of this file is elaboration on those four. Where it does not cover a case, use judgement — this is a research aid, not a procedure to execute literally.

1. Read the code first

Never search Notion to avoid reading source. Most "why" questions dissolve once the flow is actually traced — the rationale turns out to be legible in the structure, the event names, a README, or an ADR. Cheaper, more current, and more trustworthy than any document.

2. Name the gap, then ask

Before offering to search, state what the code settled and what it could not. Gaps come in two shapes and surface at different moments.

The narrow gap turns up mid-investigation. The flow is traced and one specific thing remains unexplained. State it in a sentence:

• "The Kenya builder hardcodes CostPerCredit behind a // NLOA > A7/A8 point comment. The code tells me it is a placeholder. It does not tell me what A7/A8 is or who owns closing it."
• "Five country-specific fiscal registration commands exist, and a sixth generic one was merged four months ago with no consumers. Source cannot tell me whether that is abandoned or sequenced."

For these, "I don't have full context" is not a gap. If the missing question cannot be stated in one sentence, the code is not finished being read.

The macro gap is present from the first message. Some questions are scoped beyond source from the outset — design intent across a whole platform, why a direction was chosen, what the rollout sequence is, who is affected and what to tell them. Change-management framing is the clearest tell: "how might this impact other teams, so I can start engaging them."

Do not wait to exhaust the code on these. Source will never answer them — not because the reading was insufficient, but because intent and roadmap are not in source at all. The gap is a category, not a sentence, and naming the category is enough:

Source gives you the flows, the events, and who consumes them. It cannot tell you why this shape was chosen or what the rollout intent is — that lives in the team's own documents, if anywhere.

Answer the code-answerable part first anyway. A macro question almost always has a large answerable core: the flows, the events, the handoffs, legacy versus new. Deliver that, then name what is left over, then offer. Never lead with the offer.

"The code cannot answer this" is a trigger, not a decline. Recognising the boundary and stopping there — handing the whole question back to the engineers — is the exact failure this skill exists to remove. Name the boundary, then offer the bridge across it.

Then offer in one line, and wait:

The code shows what happens here but not why it was designed this way. Want me to check Notion for an SDD or PRD on it?

No pre-emptive searching, no searching because it might turn out useful. The cost is real — time in the conversation, weight in the context — so it is the user's call each time.

Two exceptions to asking. If they invoked this skill explicitly, that is the yes; do not ask again. If they name or paste a document, skip searching entirely and hand that URL straight to the sub-agent.

3. Delegate the search to a sub-agent

Never fetch Notion pages in the main thread. Design documents run to thousands of words, and a handful of fetched pages will crowd out the code the session was spent reading. The sub-agent absorbs that weight and returns a summary measured in bullets.

Call the Agent tool with subagent_type: "general-purpose" and model: "sonnet". Open the prompt with:

Read .claude/skills/notion-design-context/references/notion-search-brief.md and follow it exactly.

That file holds the search strategy, the fetch budget, how to judge source strength, and what to return. It stays out of this conversation — the sub-agent reads it in its own context.

Then brief it. A one-line prompt returns a generic answer, so give it four things:

• The question, phrased as the gap that was named, not the user's original words.
• What the code already showed, with repo and file names. This is what lets it recognise the right document, and tell a description of the target state apart from a description of what shipped.
• The vocabulary — event names, command names, service names, countries. These are the search terms that actually hit.
• Who probably owns it, if known. Team or domain is enough.

The sub-agent finds the Notion tools itself via ToolSearch — their names carry a connector ID unique to each person, so nothing here hardcodes one. If it reports that no Notion tools exist, the user has not connected the connector. Say that in one line and stop.

Using what comes back

Code stays primary. The summary answers why. It never gets promoted to evidence of what the system currently does. A document describing a unified command as the target path is evidence of intent; the absence of any consumer in source is evidence of reality. Report both.

The delta is usually the finding. When document and code diverge, lead with the divergence. Target state that was never built, an open question the team logged and never closed, a decision reversed in code but not in the doc — say it plainly. It is more useful than either source alone, and it is exactly what a product leader needs before walking into the room.

Cite once, in one line, with a link. The first time a Notion-sourced claim appears:

The unified command is Goal #1 of the Solution Discovery Document – Billing Platform (Portfolio Operations, in progress).

That is the entire citation. No bibliography, no footnote block, no repeating it on every bullet. The link is there so the reader can check the source is the right source, and push back if it is not.

Mark it known, and qualify the status. A document is known — stated, verifiable without inference. But a draft, a stale page, or an RFC with open TBDs is known to have been written, not known to be true. Say which. A stale doc presented as settled is worse than no doc at all.

Nothing found is a real answer. If no strong source exists, say so in one line and hand over the question to put to a person. Never pad with weak documents to justify having searched.

Anti-patterns

• Declining instead of offering. "The rationale and the engagement plan are outside what I can responsibly do — you'll need the engineers for that" is correct about the boundary and wrong about what to do at it. Naming a limit is the start of the offer, not the end of the answer.
• Searching instead of reading. The code answers most why-questions. Reach for Notion when it demonstrably has not.
• Searching without asking. Silent context-gathering that costs the user time and window they did not agree to spend.
• Fetching pages in the main thread. Defeats the entire purpose. The sub-agent exists for exactly this.
• Notion as current behaviour. The most damaging failure available here. A document describes what someone intended, on the date they wrote it.
• Citation clutter. A link on every bullet, or a sources block at the bottom, buries the answer.
• A citation with no link. The reader cannot verify the source is the right one, which is the main thing they need to be able to do.
• Burying the delta. If the doc and the code disagree, that goes near the top, not in a closing caveat.
• Padding with weak sources. Meeting notes and a deck are not an SDD. Say nothing strong was found.