From cc2e6ff1a5e0abec8fb3a32aae4c8f251b24a7e1 Mon Sep 17 00:00:00 2001 From: Cascade Bot Date: Thu, 2 Apr 2026 10:04:05 +0000 Subject: [PATCH] feat(prompts): add documentation maintenance instructions to agent prompts --- .../prompts/templates/implementation.eta | 3 + .../partials/documentation-maintenance.eta | 42 ++++++ src/agents/prompts/templates/planning.eta | 1 + .../prompts/templates/resolve-conflicts.eta | 2 + .../prompts/templates/respond-to-ci.eta | 2 + .../templates/respond-to-pr-comment.eta | 3 + .../prompts/templates/respond-to-review.eta | 3 + src/agents/prompts/templates/review.eta | 11 ++ tests/unit/agents/prompts.test.ts | 127 ++++++++++++++++++ 9 files changed, 194 insertions(+) create mode 100644 src/agents/prompts/templates/partials/documentation-maintenance.eta diff --git a/src/agents/prompts/templates/implementation.eta b/src/agents/prompts/templates/implementation.eta index 8dd220c8..0e581f75 100644 --- a/src/agents/prompts/templates/implementation.eta +++ b/src/agents/prompts/templates/implementation.eta @@ -106,6 +106,8 @@ Use `PostComment` to post a summary on the <%= it.workItemNoun || 'card' %> once <%~ include("partials/test-protocol") %> +<%~ include("partials/documentation-maintenance") %> + ### Completion Protocol (CRITICAL) NEVER mark acceptance criteria or checklist items complete until ALL of: @@ -113,5 +115,6 @@ NEVER mark acceptance criteria or checklist items complete until ALL of: 2. Tests pass (zero failures) 3. Lint passes (zero errors) 4. PR is successfully created (and you have the PR number) +5. Documentation updated (if changes affect documented behavior) <%~ include("partials/rules-efficiency") %> diff --git a/src/agents/prompts/templates/partials/documentation-maintenance.eta b/src/agents/prompts/templates/partials/documentation-maintenance.eta new file mode 100644 index 00000000..a74b0eb1 --- /dev/null +++ b/src/agents/prompts/templates/partials/documentation-maintenance.eta @@ -0,0 +1,42 @@ +### Documentation Maintenance + +When your code changes affect documented behavior, update the relevant docs as part of the same PR. + +#### When to Update Docs + +Check for doc updates if your change: +- Adds, removes, or renames a public function, class, env var, or config option +- Changes how a feature behaves from the user or developer perspective +- Introduces a new architectural pattern or module convention +- Modifies setup, deployment, or configuration steps + +Skip doc updates for: internal refactors with no external behavior change, test-only changes, or +bug fixes that restore behavior already described in docs. + +#### What to Check + +- **CLAUDE.md / AGENTS.md** — Developer conventions, setup steps, commands +- **README.md** — User-facing overview, installation, usage +- **docs/** — Architecture guides, feature documentation +- **JSDoc / inline comments** — Function signatures, complex logic explanations + +#### How to Find Relevant Docs + +Use RipGrep to locate docs that reference the feature or symbol you changed: + +```bash +# Find docs mentioning a function/feature name +RipGrep(pattern="functionName|FeatureName", glob="**/*.md") + +# Find JSDoc for a specific function +RipGrep(pattern="@param|@returns", glob="src/path/to/file.ts") +``` + +#### Documentation Update Checklist + +Before marking your work complete, verify: +- [ ] Public API changes are reflected in JSDoc (params, return types, thrown errors) +- [ ] New env vars or config options are documented in CLAUDE.md or README +- [ ] New architectural patterns are noted in the relevant docs/ file +- [ ] Removed/renamed features no longer appear in docs as current behavior + diff --git a/src/agents/prompts/templates/planning.eta b/src/agents/prompts/templates/planning.eta index c7206eb1..1e5db1ce 100644 --- a/src/agents/prompts/templates/planning.eta +++ b/src/agents/prompts/templates/planning.eta @@ -36,6 +36,7 @@ You are running in a cloned copy of the project repository. Before creating your 3. **Trace integrations** - Understand how components connect (APIs, event flows, shared state, pub/sub) 4. **Map dependencies** - What libraries, utilities, and shared modules does related code use? 5. **Note conventions** - Naming patterns, file organization, error handling, logging practices +6. **Check documentation** - Scan CLAUDE.md, README.md, and docs/ to identify which docs cover the area being changed; include a doc update step in your plan if the change affects documented behavior (public APIs, env vars, architecture, setup steps) **When planning your solution:** - Reuse existing utilities and abstractions rather than creating new ones diff --git a/src/agents/prompts/templates/resolve-conflicts.eta b/src/agents/prompts/templates/resolve-conflicts.eta index 55ed7c7a..84b2600e 100644 --- a/src/agents/prompts/templates/resolve-conflicts.eta +++ b/src/agents/prompts/templates/resolve-conflicts.eta @@ -165,6 +165,8 @@ Use `UpdatePRComment` with the comment ID from session state. <%~ include("partials/test-protocol") %> +<%~ include("partials/documentation-maintenance") %> + <%~ include("partials/verification-protocol") %> <%~ include("partials/rules-efficiency") %> diff --git a/src/agents/prompts/templates/respond-to-ci.eta b/src/agents/prompts/templates/respond-to-ci.eta index f4884dbd..e8f32894 100644 --- a/src/agents/prompts/templates/respond-to-ci.eta +++ b/src/agents/prompts/templates/respond-to-ci.eta @@ -131,6 +131,8 @@ Use `UpdatePRComment` with the comment ID from session state. <%~ include("partials/test-protocol") %> +<%~ include("partials/documentation-maintenance") %> + <%~ include("partials/verification-protocol") %> <%~ include("partials/rules-efficiency") %> diff --git a/src/agents/prompts/templates/respond-to-pr-comment.eta b/src/agents/prompts/templates/respond-to-pr-comment.eta index 5c9633f5..0912ab92 100644 --- a/src/agents/prompts/templates/respond-to-pr-comment.eta +++ b/src/agents/prompts/templates/respond-to-pr-comment.eta @@ -91,6 +91,7 @@ Use `UpdatePRComment` with the comment ID from session state. - Don't make unrelated changes - If the request conflicts with codebase conventions, follow conventions and explain why - Follow existing code patterns and conventions +- If changes affect documented behavior, update relevant docs (CLAUDE.md, README, JSDoc) ### Code Quality - ALWAYS run tests and lint before committing @@ -99,6 +100,8 @@ Use `UpdatePRComment` with the comment ID from session state. <%~ include("partials/test-protocol") %> +<%~ include("partials/documentation-maintenance") %> + <%~ include("partials/verification-protocol") %> <%~ include("partials/rules-efficiency") %> \ No newline at end of file diff --git a/src/agents/prompts/templates/respond-to-review.eta b/src/agents/prompts/templates/respond-to-review.eta index 20ae51d9..3753b2ba 100644 --- a/src/agents/prompts/templates/respond-to-review.eta +++ b/src/agents/prompts/templates/respond-to-review.eta @@ -86,6 +86,7 @@ Fixed! Updated the function to handle the edge case by adding a null check at li - Reply to EACH comment after fixing it - If you can't address a comment (unclear, out of scope, disagree), reply explaining why - Follow existing code patterns and conventions +- If changes affect documented behavior, update relevant docs (CLAUDE.md, README, JSDoc) ### Code Quality - ALWAYS run tests and lint before committing @@ -94,6 +95,8 @@ Fixed! Updated the function to handle the edge case by adding a null check at li <%~ include("partials/test-protocol") %> +<%~ include("partials/documentation-maintenance") %> + <%~ include("partials/verification-protocol") %> <%~ include("partials/rules-efficiency") %> diff --git a/src/agents/prompts/templates/review.eta b/src/agents/prompts/templates/review.eta index 05b901f0..8795dd32 100644 --- a/src/agents/prompts/templates/review.eta +++ b/src/agents/prompts/templates/review.eta @@ -154,6 +154,17 @@ Style and preferences - mention only if egregious: - **Build-time config**: For features requiring build-time injection, verify the injection point exists - **When uncertain**: Ask in your review rather than assuming deployment is configured correctly +### Documentation +- **Currency**: Do CLAUDE.md, README.md, and docs/ still accurately describe features changed by this PR? +- **New features**: Are user-facing or developer-facing features introduced without any documentation? +- **Stale references**: Does the PR remove or rename something that's still referenced in docs? +- **JSDoc**: Are new public functions/classes missing parameter or return type documentation? + +Severity guide: +- Missing docs for a user-facing feature or new env var = **SHOULD_FIX** +- Missing JSDoc on a new public API = **NITPICK** +- Actively misleading docs (describe behavior that no longer exists) = **SHOULD_FIX** + ## Strategic Questions Answer these during Phase 1 — they catch design problems that line-by-line review misses: diff --git a/tests/unit/agents/prompts.test.ts b/tests/unit/agents/prompts.test.ts index 7873ba80..10a2741a 100644 --- a/tests/unit/agents/prompts.test.ts +++ b/tests/unit/agents/prompts.test.ts @@ -15,6 +15,7 @@ vi.mock('../../../src/agents/definitions/index.js', () => ({ 'respond-to-planning-comment', 'debug', 'backlog-manager', + 'resolve-conflicts', ]), })); @@ -398,6 +399,7 @@ describe('readTemplateFileSync', () => { 'respond-to-planning-comment', 'debug', 'backlog-manager', + 'resolve-conflicts', ]; for (const agentType of builtinTypes) { const content = readTemplateFileSync(agentType); @@ -655,6 +657,7 @@ describe('duplicate content detection', () => { 'respond-to-planning-comment', 'debug', 'backlog-manager', + 'resolve-conflicts', ]; for (const agentType of allAgentTypes) { @@ -827,3 +830,127 @@ describe('squintEnabled template gating', () => { expect(rendered).not.toContain('squint-features'); }); }); + +describe('documentation-maintenance partial', () => { + it('partial exists in getAvailablePartialNames()', () => { + const names = getAvailablePartialNames(); + expect(names).toContain('documentation-maintenance'); + }); + + it('partial contains key doc-update phrases', () => { + const content = getRawPartial('documentation-maintenance'); + expect(content).toContain('CLAUDE.md'); + expect(content).toContain('README'); + expect(content).toContain('JSDoc'); + expect(content).toContain('docs/'); + }); + + it('partial describes when to update docs (conditional guidance)', () => { + const content = getRawPartial('documentation-maintenance'); + expect(content).toContain('When to'); + }); + + it('partial provides a documentation update checklist', () => { + const content = getRawPartial('documentation-maintenance'); + expect(content).toContain('Documentation Update Checklist'); + }); +}); + +describe('documentation maintenance in code-modifying agent prompts', () => { + it('implementation prompt contains documentation maintenance section', () => { + const prompt = getSystemPrompt('implementation'); + expect(prompt).toContain('Documentation Maintenance'); + expect(prompt).toContain('CLAUDE.md'); + expect(prompt).toContain('JSDoc'); + }); + + it('implementation prompt completion protocol includes documentation step', () => { + const prompt = getSystemPrompt('implementation'); + expect(prompt).toContain('Documentation updated'); + }); + + it('respond-to-review prompt contains documentation maintenance section', () => { + const prompt = getSystemPrompt('respond-to-review'); + expect(prompt).toContain('Documentation Maintenance'); + expect(prompt).toContain('CLAUDE.md'); + }); + + it('respond-to-review prompt scope section mentions documentation updates', () => { + const prompt = getSystemPrompt('respond-to-review'); + expect(prompt).toContain('documented behavior'); + }); + + it('respond-to-ci prompt contains documentation maintenance section', () => { + const prompt = getSystemPrompt('respond-to-ci'); + expect(prompt).toContain('Documentation Maintenance'); + expect(prompt).toContain('CLAUDE.md'); + }); + + it('respond-to-pr-comment prompt contains documentation maintenance section', () => { + const prompt = getSystemPrompt('respond-to-pr-comment'); + expect(prompt).toContain('Documentation Maintenance'); + expect(prompt).toContain('CLAUDE.md'); + }); + + it('respond-to-pr-comment prompt scope section mentions documentation updates', () => { + const prompt = getSystemPrompt('respond-to-pr-comment'); + expect(prompt).toContain('documented behavior'); + }); + + it('resolve-conflicts prompt contains documentation maintenance section', () => { + const prompt = getSystemPrompt('resolve-conflicts'); + expect(prompt).toContain('Documentation Maintenance'); + expect(prompt).toContain('CLAUDE.md'); + }); +}); + +describe('documentation review checks in review agent', () => { + it('review prompt contains Documentation subsection under What to Verify', () => { + const prompt = getSystemPrompt('review'); + expect(prompt).toContain('### Documentation'); + }); + + it('review prompt covers documentation currency', () => { + const prompt = getSystemPrompt('review'); + expect(prompt).toContain('Currency'); + }); + + it('review prompt covers undocumented new features', () => { + const prompt = getSystemPrompt('review'); + expect(prompt).toContain('New features'); + }); + + it('review prompt covers stale references in docs', () => { + const prompt = getSystemPrompt('review'); + expect(prompt).toContain('Stale references'); + }); + + it('review prompt includes SHOULD_FIX severity for missing user-facing docs', () => { + const prompt = getSystemPrompt('review'); + expect(prompt).toContain('SHOULD_FIX'); + }); + + it('review prompt does NOT include documentation-maintenance partial (reports gaps, does not fix)', () => { + const prompt = getSystemPrompt('review'); + // The partial's checklist heading should not be present in review + expect(prompt).not.toContain('Documentation Update Checklist'); + }); +}); + +describe('documentation planning in planning agent', () => { + it('planning prompt contains documentation check as step 6 in pattern analysis', () => { + const prompt = getSystemPrompt('planning'); + expect(prompt).toContain('Check documentation'); + }); + + it('planning prompt includes guidance to add doc update steps to plans', () => { + const prompt = getSystemPrompt('planning'); + expect(prompt).toContain('doc update step'); + }); + + it('planning prompt does NOT include documentation-maintenance partial', () => { + const prompt = getSystemPrompt('planning'); + // The partial's checklist heading should not be in planning prompt + expect(prompt).not.toContain('Documentation Update Checklist'); + }); +});