Documenting development work

Give every document one authoritative home. Persist only information that must outlive the conversation; use pointers instead of maintaining the same content in GitHub, Markdown, and generated artifacts.

1. Classify the persistence tier

Choose one tier before writing:

• Conversation: analysis, draft, diagnosis, or review needed only for the current interaction. Return it in the response; create no file.
• Tracker: issue brief, ticket graph, implementation evidence, or issue-backed handoff whose lifecycle is owned by GitHub. Store it in the issue, PR, comment, or native relationship.
• Repository: approved knowledge or local coordination state that must be reviewed and versioned with the code, such as a domain model, spec, decision map, local-work set, decision, durable research result, or explicitly controlled derivative.
• Artifact store: generated logs, traces, screenshots, benchmark output, or run evidence. Use the repository's artifact system and retention policy; do not turn raw output into product documentation.

A request to inspect, explain, review, or draft selects Conversation unless the user or repository contract requests persistence. A request to save, record, publish, or create a named repository document authorizes that document plus locally required index entries and in-repository reciprocal links. Tracker comments, issue edits, and other external pointers require separate mutation authorization.

2. Resolve the repository contract

Apply this precedence: