Skip to content

feat: add documentation staleness checks to issue-lifecycle skill#911

Open
stack72 wants to merge 1 commit intomainfrom
issue-lifecycle-doc-staleness
Open

feat: add documentation staleness checks to issue-lifecycle skill#911
stack72 wants to merge 1 commit intomainfrom
issue-lifecycle-doc-staleness

Conversation

@stack72
Copy link
Copy Markdown
Contributor

@stack72 stack72 commented Mar 29, 2026

Summary

  • Adds a documentation impact check as a new planning step (step 6) in the issue-lifecycle skill, requiring plans to evaluate whether changes affect design/*.md or .claude/skills/ and include update steps if so
  • Adds "Documentation" as a new adversarial review dimension alongside architecture, scope, risk, testing, complexity, and correctness
  • Adds stale doc/skill verification to the codebase verification checklist, so the adversarial reviewer actively checks referenced design docs and skills against planned changes
  • Adds documentation as a valid finding category for adversarial review findings

Why

Design docs and skills drift out of sync with the codebase when PRs change behavior without updating the documentation that describes it. This is hard to catch after the fact because the people making changes have the context at planning time but not later. By embedding the check into the issue-lifecycle adversarial review — which already blocks approval on unresolved findings — we catch documentation gaps before code is written, when the fix is cheap.

Impact

Every issue triaged through the issue-lifecycle model will now have documentation impact evaluated at two points:

  1. Planning — the plan must include doc/skill update steps if the change warrants them
  2. Adversarial review — gaps are flagged as findings that block approval if severity is high/critical

This is a skill-only change with no code changes. It modifies the instructions that guide Claude's behavior during issue triage and plan review.

Test plan

  • Triage a test issue that changes CLI behavior and verify the plan includes a skill update step
  • Triage a test issue that changes domain concepts and verify the adversarial review flags missing design doc updates
  • Triage a trivial bug fix and verify no false-positive documentation findings are raised

🤖 Generated with Claude Code

The issue-lifecycle adversarial review now checks whether planned changes
affect design docs or skills that need updating. This catches documentation
drift at planning time rather than after the fact.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@stack72 stack72 force-pushed the issue-lifecycle-doc-staleness branch from f305c97 to df538b8 Compare March 29, 2026 01:10
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.

1 participant