Skip to content

Comments

Add spec docs drift audit deliverables#1

Closed
justyn-clark wants to merge 2 commits intomainfrom
claude/audit-spec-docs-drift-HCzRg
Closed

Add spec docs drift audit deliverables#1
justyn-clark wants to merge 2 commits intomainfrom
claude/audit-spec-docs-drift-HCzRg

Conversation

@justyn-clark
Copy link
Owner

Deliverables:

  • DRIFT_REPORT.md: 15 drift issues identified (2 critical, 6 major, 7 minor)
  • PATCH_PLAN.md: Sequenced patch plan grouped by category
  • CANONICAL_COPY_BLOCKS.md: Reusable copy blocks for correct SMALL framing

Key findings:

  • "Execution protocol" language drift in FAQ.md
  • Missing CLI commands in reference docs (start, fix)
  • Agent contract shows old validate/lint pattern instead of unified check
  • First-run guides missing self-healing commands

All deliverables are deterministic and copy-pastable per requirements.

Deliverables:
- DRIFT_REPORT.md: 15 drift issues identified (2 critical, 6 major, 7 minor)
- PATCH_PLAN.md: Sequenced patch plan grouped by category
- CANONICAL_COPY_BLOCKS.md: Reusable copy blocks for correct SMALL framing

Key findings:
- "Execution protocol" language drift in FAQ.md
- Missing CLI commands in reference docs (start, fix)
- Agent contract shows old validate/lint pattern instead of unified check
- First-run guides missing self-healing commands

All deliverables are deterministic and copy-pastable per requirements.
Changes:
- AGENTS_MD_AUDIT.md: Audit of provided AGENTS.md against current CLI doctrine
- AGENTS.md: Updated agent quick-reference guide with correct CLI patterns

Key improvements to AGENTS.md:
- Added self-healing commands (start, fix, doctor) to agent-safe command set
- Renamed "Ralph loop" to "Work loop" for clarity
- Added session start self-healing workflow
- Added init vs start clarification
- Enhanced doctor command description
- Added troubleshooting section with self-healing workflow

Audit found no major doctrinal drift - the guide already used correct
state governance framing and checkpoint/check --strict workflows.
Updates focus on CLI command completeness and workflow clarity.
@justyn-clark justyn-clark deleted the claude/audit-spec-docs-drift-HCzRg branch January 25, 2026 00:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants