44 lines
1.8 KiB
Markdown
44 lines
1.8 KiB
Markdown
# 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:
|
|
|
|
1. Do not silently overwrite.
|
|
2. Add the conflict to `stale-items.md`.
|
|
3. 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.
|