| name | docs-sync |
| description | Synchronizes review feedback, QA findings, user corrections, and code-review suggestions into durable project docs before Build, merge, or ship. |
Docs Sync — Review Feedback to Project Docs
Status: Operational workflow. Use this skill when feedback changes project knowledge that must survive beyond chat.
Review feedback is not complete until it is either:
- Applied in code and reflected in the affected docs; or
- Explicitly deferred / rejected with rationale in the appropriate project doc.
Conversation-only feedback is not durable.
When to use
Use this workflow after:
- user review feedback
- QA findings
- code-review suggestions
- design review comments
- architecture review comments
- bug reports or regression discoveries
- deferred cleanup or refactor suggestions
- any Build / Review / Test / Ship correction that changes lasting project knowledge
Feedback classification matrix
| Feedback type | Required docs |
|---|
| Scope / business goal / success criteria | docs/PROJECT-OVERVIEW.md + docs/PRD.md + docs/QA-TRACKER.md |
| User story / acceptance criteria | docs/PRD.md + docs/QA-TRACKER.md |
| UI / UX / component / copy / layout | docs/DESIGN.md + docs/TEST-COVERAGE.md |
| API contract / endpoint / error code / wire shape | docs/API.md + docs/TEST-COVERAGE.md |
| Architecture / data model / infrastructure | new or updated ADR under docs/architecture/ + affected docs |
| Test gap / QA finding | docs/QA-TRACKER.md + docs/TEST-COVERAGE.md |
| Bug / regression risk | docs/REGRESSION-GUARD.md + docs/TEST-COVERAGE.md + related docs/QA-TRACKER.md row |
| Refactor / cleanup / known trade-off | docs/TECH-DEBT.md |
| Dependency / external package assumption | docs/TECH-DEBT.md and ADR / retro if architectural or incident-derived |
| Rejected suggestion | affected doc changelog / notes or docs/TECH-DEBT.md with rationale |
Workflow
- Inventory each feedback item.
- Classify each item using the matrix.
- Assign one status per item:
applieddeferredrejectedneeds David decision
- Update affected docs before or in the same change as code.
- Keep
docs/PRD.md and docs/QA-TRACKER.md synchronized for every US-* change.
- For bug fixes, create or update the
RG-XXX entry and regression coverage.
- Run verification commands.
- Final response must include:
- feedback items handled
- docs updated
- deferred / rejected items and rationale
- unresolved questions
- verification commands and results
Verification
Run from the repository root:
python3 scripts/docs_consistency_check.py
python3 scripts/docs_consistency_check.py --project-docs
python3 scripts/docs_consistency_check.py --project-docs --base-ref origin/main --doc-code-sync
git status --short
git diff --name-only
If a command fails because the downstream project documentation baseline intentionally does not exist yet, report the failure and whether it is expected for the current repository state. Do not hide failed verification.
Final report format
## Docs Delta
- Feedback items handled:
- Docs updated:
- Deferred items:
- Rejected items:
- Needs David decision:
- Verification run:
- Docs intentionally not updated and why:
Related docs
