Source handling

How to gather and reconcile the raw material without quietly inventing things.

Establish scope first

Do not start reading until you can answer:

1. What question must the page answer, for whom?
2. Which repos, folders, Confluence spaces and tickets hold the truth?
3. What is the page's cadence — one-off brief, or a living status page someone rebuilds monthly?

The third answer changes the build. A living page needs the regeneration block and its source committed; a one-off brief can skip both.

Gathering

From repos. Read every listed document in full. Never infer a plan's status from its filename or first paragraph. Paths move — if a document is not where it was, search the docs tree and follow each document's own related_docs frontmatter to find its current neighbours. Where a repo follows docs-lifecycle-convention, wip/ holds the live plans and core/architecture/ the settled shape.

Across repos. Name the repo alongside every path in the Sources section — a bare deployment.md is ambiguous once two repos are in scope. If the repos are not already cloned locally, use sync-portfolio-repos rather than guessing clone paths.

From Confluence. Extracts are point-in-time copies, so record the page title, space, and the date you pulled it, and say so on the page. Confluence tables often carry the status a repo document has not caught up with — and sometimes the reverse. Neither wins automatically; see below.

From effort JSON and trackers. These drift. Prefer a plan's own headline status table over deeper step-level JSON when the two disagree — the table is what the author is claiming as current truth. If you rely on the JSON instead, say so on the page.

Fidelity rules

1. Read fully before summarising. A summary of a summary is where errors enter.
2. Never invent a number, date, name, or status. A fact with no source stays out of the page, or goes into an open-questions section as a question — never as a stated fact.
3. Flag provisional figures as provisional when the sources say they are. Do not silently present hand-tracked estimates as settled.
4. When two sources disagree, do not pick one silently. Prefer whichever has the later "Last updated" date, and add a one-line callout if the disagreement is material to a reader's decision.
5. Default to role descriptions over named individuals — except where a named person is structural to the plan itself, such as a transitional access role tied to one person. That distinction is usually the point being made.
6. Keep exact technical tokens verbatim. Branch names, env vars, role names, ticket prefixes, table names. Set them in monospace and never paraphrase them — a reader will copy them.

Authored input

Everything above assumes you are deriving the page from documents. An authored overview is the exception: a markdown file, or a paste in the conversation, that a named person wrote and expects to appear as they wrote it.

Treat it as verbatim input. The rules in the skill's Optional: an authored overview section govern it, and they invert two of the fidelity rules here:

Normally	With an authored overview
Your own opinion about the plan stays out	The author's opinion is the content
When two sources disagree, add a callout	The author is usually a co-author of the plans, updating their own view. No callout
A hedged claim becomes an open question	A hedge stays exactly as written

The one thing you still owe the author is a reply, not a page edit. If a source document states something more strongly or more weakly than they have, say so in your response so they can decide. Never resolve it silently, in either direction.

Writing for a mixed audience

The reader is a trading desk lead or a platform engineer, and you do not know which.

• Explain each piece of jargon in plain language the first time it appears, then use the real technical term. Not a glossary — inline, once.
• Lead each section with the claim, then the evidence. A heading that says "Two changes, one safety pattern" earns its place; one that says "Overview" does not.
• Prose over bullets. Reserve lists for genuinely enumerable content: open questions, file lists, role tables. Any list over three items uses numbers or letters so an item can be pointed at in a meeting.
• Numbers lead, units spelled out, tabular figures so columns align.

What goes on the page versus what stays out

Material	Where it belongs
A figure with a source and a date	On the page, with the date
A figure someone quoted in a meeting	Out, or as an open question
A decision with an ADR	On the page, linked
A decision "everyone knows"	Out — write the ADR first
A disagreement between two docs	On the page, as a callout, if material
A risk already registered in the plan	On the page
Your own opinion about the plan	Out