record

# Record Knowledge Record significant decisions for future work. Reconcile the affected requirements and system designs after the decision. ## Record a decision Create an ADR when all statements are true: - The choice creates a durable constraint, boundary, contract, ownership rule, operational invariant, or repository-wide convention. - Meaningful alternatives have different trade-offs. - Future work must follow or supersede the choice. - A requirement, system design, test, or work order does not preserve enough rationale. Do not create an ADR for a simple feature, local refactor, routine dependency change, plan sequence, or temporary migration step. ## ADR procedure 1. Choose an ID in the form `YYYY-MM-DD-short-title`. 2. Make sure that `docs/decisions/<id>.md` does not exist. 3. Create the ADR with the template below. 4. Run `python3 scripts/list-docs.py decisions --format paths` to confirm the new ADR is discoverable. Do not edit a catalog row. 5. Reconcile affected specifications. Existing numeric ADR IDs remain valid. Do not rename them. ```markdown # ADR-YYYY-MM-DD-short-title: Short title **Status:** accepted | superseded by <adr-id> | deprecated **Date:** YYYY-MM-DD **Area:** backend | frontend | infra | protocol | workflow ## Context Explain the situation and the need for a decision. ## Decision State the selected rule, boundary, or contract. ## Consequences State benefits, costs, and follow-up constraints. ## Alternatives Considered State each meaningful alternative and why it was not selected. ``` ## Reconcile specifications Read `docs/specs/README.md`, the owning system `README.md`, and the relevant files in `docs/specs/guide/`. Use the catalog command to locate the owning requirements and designs. Apply these rules: - Confirm the owning system from the durable contract. Do not assign ownership to UI only because users observe the decision there. - If the decision changes observable behavior, update the owning requirement and its `REQ-*` or `AC-*` criteria. - If the decision changes technical boundaries or contracts, update the owning system design. - If both change, update both artifacts and preserve their references. - If the decision is internal and does not change a documented design, the ADR is sufficient. - If no product system applies, state that fact in the ADR. Do not copy the ADR into requirements or system design. Link the ADR from the affected design. Requirements contain observable outcomes, not decision rationale. During legacy migration, use this command to locate existing sources: python3 scripts/list-docs.py specs --kind legacy --format paths Do not create a new generic `spec.md` file. ## Validation Run: ```bash python3 scripts/lint-spec-files.py --all python3 scripts/list-docs.py validate git diff --check -- docs/decisions docs/specs ``` Report the ADR, affected requirement IDs, affected system designs, and the validation result.