# 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.