DOC_ROLES.md

Doc Roles

Canonical reference for what each tracked doc is for, and the rules about how they relate. AGENTS.md keeps a pointer to this file rather than the full content; read here when navigating docs or deciding where new content belongs.

Canonical docs (top-level scope authority)

• docs/PLAN.md — open-beta milestone order, status, current focus, and the primary next doc. Copies the Do It List.
• docs/PRODUCT_SPEC.md — global product behavior and invariants.
• docs/BACKLOG.md — post-MVP and deferred work only.
• docs/UX_GUARDRAILS.md — global UX, accessibility, and interaction rules.

Keep these in sync with every merge or scope change.

Doc-tree roles

• docs/PLAN.md — milestone-level progress only; each milestone should check off once there.
  • If PLAN.md has a Next action, keep it milestone-level; do not pull phase-level or strategy-detail steps into it.
• docs/milestones/** — phase-level execution docs: objective/status summary, phase rollup, current focus, phase-level next actions, phase checkoffs, and milestone exit criteria.
  • Every milestone represents its phases explicitly; small size is not a reason to omit phase structure.
  • For a small milestone whose phases do not warrant separate strategy docs, the milestone doc owns the phase headings and their detailed ordered checklists directly.
  • If a milestone doc has a current focus or next action, keep it phase-level. It may point to the current phase strategy, but do not pull strategy-level checklist detail into the milestone doc.
• docs/specs/** — detailed feature and domain requirements.
• docs/strategies/** — ordered implementation checklists, sequencing, and verification steps for one milestone phase. The "do this in this order" docs for active execution.
• docs/ops/** — rollout, contributor, and deployment runbooks.
• docs/qa/** — findings, test plans, verification notes, and archive material.

Strategy doc rules

• Authority: strategy docs own ordered execution sequencing for an active workstream. They are authoritative for "what do we do next?" and resumption context, but not canonical for product scope or behavior — canonical requirements still live in PLAN.md, PRODUCT_SPEC.md, and the relevant docs/specs/** files.
• Reference, don't repeat: link standing workflow rules, specs, and runbooks instead of restating them. Keep phase-specific actions and sequencing explicit, including safety-critical ordering.
• Breakout threshold: create a separate strategy doc when a phase's size, sequencing, or verification depth warrants the breakout. Do not create a one-phase strategy merely for filename symmetry; keep a small phase's detailed checklist in its milestone doc.
• Retrospective reconstruction: when backfilling historical docs, label reconstructed phase boundaries explicitly and cite the implementation/history evidence. Do not present inferred phase names or checkpoints as contemporaneous planning facts.
• Subagent-aware authoring: even when a workstream has one primary critical path, write strategy docs with subagent use in mind — keep the main ordered sequence explicit, but call out any known safe parallel sidecars or path-scoped tasks so multi-agent execution does not have to improvise.
• Owner labels: when assigning work by owner, use Guided User for tasks that require user-side account access or clicks but where the user should be coached through unfamiliar tooling; reserve plain User for work the user can drive directly without coaching.
• Item depth: nest as deep as the work requires — two levels is not a ceiling. Expand an item when a sub-item carries something the parent doesn't: a decision input, a distinct failure mode, a separate owner, or its own verification. A comma-separated list of steps is the usual tell that a checklist got flattened into one line; a comma-separated list of values is not. Leave genuinely atomic items alone rather than subdividing for symmetry.
• Every checkbox is work: at every level, a checked box means someone did something. Facts, rationale, and properties don't earn a box — fold them into the wording of the item that does the work. Depth is not a licence to give inactionable content its own line.
• Actionable phrasing: lead with the observation. Do Y if X hides the work of noticing X and reads as a caveat; write the check as the action and hang the response off it as sub-items.
• State scope, don't defend it: wording that changes what gets done belongs in the item. A sentence explaining why the scope was chosen is journaling — it goes in the commit message, not the checklist.
• Lifecycle: strategy docs may or may not be retired, archived, or folded into milestone/history docs after completion.

Checklist-depth separation

• docs/PLAN.md owns milestone checkoffs.
• docs/milestones/** always own explicit phase representation and phase checkoffs.
• docs/strategies/** own the ordered checklist for one phase when that phase is broken out into a strategy doc.
• In a strategyless small milestone, the milestone doc owns both the explicit phase checkoff and that phase's detailed ordered checklist.
• Higher-level docs roll up lower-level completion with a single checkoff instead of duplicating items.
• For any active workstream, keep one obvious checklist owner. If a milestone doc and a strategy doc both exist, the milestone doc summarizes status/objectives while the strategy doc owns the detailed ordered checklist (unless docs explicitly say otherwise).
• Any doc with numbered tasks/milestones/todos is assumed to be done in order unless that doc explicitly says otherwise — flag intentional deviations.

Do It List mirror

1. The CryptoZing Initiative is the to-do list. PLAN.md, milestone docs, and strategy docs copy it.
2. Change the Initiative first, then the doc, in the same session. Read the docs freely; check the Initiative before changing it.
3. Shape: milestone, then phase, then action group, then item. Exit Criteria sit under their milestone or phase.
4. Each checklist line ends with its Task's %<number>. Old stamps from before 2026-09-29 are Task ids: read %<412> as %<i412>.
5. Finish an item with done %<number> --mirror <doc> --section "<heading>". Tick headings by hand.
6. Add or rename an item in the Initiative, then make the doc match word for word.
7. Keep items under 200 characters. Put extra notes on an indented line below; it becomes the description.
8. Write notes inside a checklist as plain text, not bullets. Bullets become Tasks.

Reference notation

• Milestone/phase references — in commit-message prefixes and doc cross-references — use dotted M<milestone>.<phase> and extend one dotted segment per level as deep as needed (e.g., M19.5.1, M19.5.1.9, M19.5.1.9.5).
• Vocabulary: sections divide into items and subitems. "Item" may refer to an entry at any level below phase; "subitem" may refer to any item below section level.

CHANGELOG conventions

• Keep docs/CHANGELOG.log updated alongside canonical docs when scope or doc structure shifts.
• Maintain CHANGELOG.log as plain text in chronological order (oldest first); append new entries at the bottom instead of prepending.

Findings conventions

• New findings/bugs/todos go to GitHub Issues, not new finding docs. They are opened as GitHub Issues and closed via Fixes #N on the merging PR; strategy docs reference the Issue number rather than spawning a new docs/qa/Finding*.md. Existing finding docs under docs/qa/Finding*.md remain valid and unchanged. (Settled at M20 kickoff — the M19 trial is now the standing convention.)
• Each existing finding under docs/qa/Finding*.md records Date: (when reported) near the top, and adds a Date fixed: line once resolved with a brief reference to the milestone, PR, or commit that resolved it.
• A finding without a Date fixed: line is treated as still open.
• Filing is not discharging. An Issue is where a finding is stored, not a way to stop owning it. Every Issue our work raises gets named as exit criteria somewhere — the current phase preferred, otherwise a future phase or milestone. An Issue standing as exit criteria is encouraged, not a smell.

Issue content conventions

Applies to any GitHub Issue we file.

• Required: the problem — what's wrong, what's happening vs. expected, or what's missing.
• Optional: reproduction steps, file/line refs, fix direction, scope, test plan. Include when it helps the doer.
• Never: decision-journaling (## How surfaced, ## Reversibility, ## Why X over Y), internal shorthand (Path A), who-said-what narrative.
• Always link the strategy doc / spec section the work traces to (Tracked in: …).
• Write for a reader without the originating conversation; body + links should be enough to act.