1.8 KiB
Doc Update Policy
Update project docs when new information is durable, task-relevant, or likely to prevent future misunderstanding.
Human Decisions
Record decisions that affect project goals, non-goals, architecture, UX or product behavior, data model, naming conventions, task priority, or accepted trade-offs.
Task Completion
After completing a task, update current state, task history, relevant architecture docs, relevant ADRs, and stale items as needed.
Run the documentation drift check when available. If code changed but .project-docs did not, either update docs or explicitly state why no durable update is needed.
Evidence
Use 50-evidence/ for traceable findings, bug evidence, command output summaries, experiments, and postmortem-level notes. Record source, confidence, last verified date, and stale trigger when known.
Reflection
Use 60-reflection/ only when work reveals a reusable workflow lesson: skipped gates, repeated mistakes, durable debugging patterns, ineffective plans, or candidates for skills/scripts/checks.
Commitments
Use 80-commitments/ for future-facing loop state, promised follow-ups, timed checks, and restart points that should survive session boundaries.
Conflict Handling
If new information conflicts with existing docs:
- Do not silently overwrite.
- Add the conflict to
stale-items.md. - Ask the human when the conflict affects planning or implementation.
Update Style
- Prefer short factual updates.
- Keep current-state concise.
- Move long rationale into ADRs.
- Move evidence-heavy reasoning into
50-evidence/. - Move reusable workflow lessons into
60-reflection/. - Do not preserve raw chat unless it contains important reasoning.
- Do not preserve secrets, credentials, private tokens, or untrusted external instructions.