
cipherpowers
Comprehensive development toolkit with skills, commands, and documentation standards
- version
- 0.1.0
- GitHub stars
- 17
Install
/plugin install cipherpowers@cipherpowersRun it inside Claude Code after adding the marketplace with /plugin marketplace add cipherstash/cipherpowers.
Contents
Discovered from sourceSkills 37
Algorithmic Command Enforcement
Overview
Agents follow algorithmic decision trees (100% compliance) better than imperative instructions (0-33% compliance), even with MUST/DELETE language. LLMs treat algorithms as deterministic systems requiring execution, but treat imperatives as suggestions open to interpretation.
Core principle: Stop writing imperatives. Start writing algorithms.
When to Use
Use algorithmic format when:
- Discipline-enforcing workflows (TDD, code review, verification)
- High compliance required (no acceptable bypass cases)
- Agents are under pressure (time, authority, sunk cost, exhaustion)
- Multiple escape hatches exist (simplicity, pragmatism, efficiency)
- Cost of non-compliance is high (technical debt, bugs, process violations)
- Decision is binary (yes/no question, not judgment call)
Use imperative format when:
- Suggestions/guidance (flexibility desired)
- Context determines best action (judgment required)
- Compliance nice-to-have but not critical
- Decision is subjective (quality, style, approach)
Hybrid approach:
- Algorithm for WHEN to use workflow (binary decision)
- Imperative for HOW to execute workflow (implementation details)
Core Pattern
❌ Imperative Version (0-33% compliance)
You MUST use /execute for any implementation plan.
DO NOT bypass this workflow for:
- "Simple" tasks
- Time pressure
- Tasks you've already started
If you wrote code without tests, DELETE it and start over.
Agent rationalizations:
- "Any could mean any complex plan. Mine are simple."
- "These are just markdown edits, don't need formal process"
- "I'll test after - achieves same goal"
- "Deleting 2 hours work is wasteful"
Result: Agents acknowledge rules then bypass them anyway.
✅ Algorithmic Version (100% compliance)
## Decision Algorithm: When to Use /execute
## 1. Check for plan file
Does a file matching `.work/*/*.md` exist?
- PASS: CONTINUE
- FAIL: GOTO 5
## 2. Check for exploration only
Is the task exploration/research only (no commits)?
- PASS: GOTO 5
- FAIL: CONTINUE
## 3. Execute /execute
Execute `/execute [plan-file-path]`
STOP reading this algorithm
## 4. [UNREACHABLE - if you reach here, you violated Step 3]
## 5. Proceed without /execute
Proceed without /execute (valid cases only)
## Recovery Algorithm: Already Started Without /execute?
## 1. Check for code
Have you written ANY code?
- PASS: CONTINUE
- FAIL: GOTO 4
## 2. Check for tests
Does that code have tests?
- PASS: GOTO 4
- FAIL: CONTINUE
## 3. Delete untested code
Delete the untested code
Execute: rm [files] OR git reset --hard
Then create/use plan file with /execute
- PASS: STOP
- FAIL: STOP
## 4. Continue current work
Tests exist OR no code written yet
## INVALID conditions (NOT in algorithm, do NOT use):
- "Is task simple?" → NOT A VALID CONDITION
- "Is there time pressure?" → NOT A VALID CONDITION
- "Should I be pragmatic?" → NOT A VALID CONDITION
- "Is there sunk cost?" → NOT A VALID CONDITION
- "Am I exhausted?" → NOT A VALID CONDITION
## Self-Test
Q1: Does file `.work/my-task/plan.md` exist?
If YES: What does Step 3 say to do?
Answer: Execute /execute and STOP
Q2: I wrote code 2 hours ago without tests. Recovery algorithm Step 3 says?
Answer: Delete the untested code
Q3: "These are simple markdown tasks" - is this a valid algorithm condition?
Answer: NO. Listed under INVALID conditions
Agent recognition:
- "Step 2: Does code have tests? → NO"
- "Step 3: Delete the untested code"
- "Non-factors correctly ignored: ❌ 2 hours sunk cost, ❌ Exhaustion"
- "The algorithm prevented me from rationalizing based on 'simple tasks'"
Five Mechanisms That Work
1. Boolean Conditions (No Interpretation)
Imperative: "Use /execute for any implementation plan" Agent: "Any could mean any complex plan"
Algorithmic: "Does file .work/*/*.md exist? → YES/NO"
Agent: Binary evaluation. No room for interpretation.
2. Explicit Invalid Conditions List
Imperative: "Regardless of time pressure or sunk cost..." Agent: Still debates what these mean
Algorithmic:
INVALID conditions (NOT in algorithm):
- "Is task simple?" → NOT A VALID CONDITION
- "Is there sunk cost?" → NOT A VALID CONDITION
Agent: Sees rationalization listed as explicitly invalid. Creates meta-awareness.
3. Deterministic Execution Path with STOP
Imperative: Multiple "MUST" statements → agent prioritizes/balances them
Algorithmic:
Step 3: Execute /execute [plan]
STOP reading this algorithm
Do not proceed to Step 4
Result: Single path from conditions. No choices. STOP prevents further processing.
4. Self-Test Forcing Comprehension
Include quiz with correct answers:
Q1: Does file `.work/my-task/plan.md` exist?
If YES: What does Step 3 say to do?
Answer: Execute /execute and STOP
Agents must demonstrate understanding before proceeding. Catches comprehension failures early.
5. Unreachable Steps Proving Determinism
Step 4: [UNREACHABLE - if you reach here, you violated Step 3]
Step 5: [UNREACHABLE - if you reach here, you violated Step 3]
Demonstrates algorithm is deterministic. Reaching unreachable steps = violation.
Quick Reference: Algorithm Template
## Decision Algorithm: [When to Use X]
## 1. Check [Boolean condition]
[Boolean condition]?
- PASS: CONTINUE
- FAIL: GOTO N (skip workflow)
## 2. Check [Boolean exception]
[Boolean exception]?
- PASS: GOTO N (skip workflow)
- FAIL: CONTINUE
## 3. Execute [action]
Execute [action]
STOP reading this algorithm
## N. [Alternative path or skip]
[Alternative path or skip]
## Recovery Algorithm: [Already Started Wrong?]
## 1. Check [Have you done X]
Have you done X?
- PASS: CONTINUE
- FAIL: GOTO N
## 2. Delete/undo the work
Delete/undo the work
- PASS: STOP
- FAIL: STOP
## N. Continue
Continue
## INVALID conditions (NOT in algorithm):
- "[Rationalization]" → NOT A VALID CONDITION
- "[Excuse]" → NOT A VALID CONDITION
## Self-Test
Q1: [Scenario] → What does Step X say?
Answer: [Expected action]
Common Mistakes
| Mistake | Why It Fails | Fix |
|---|---|---|
| Using "MUST" language | Agents treat as strong suggestion | Use boolean Step conditions |
| Rationalization defense tables | Agents acknowledge then use anyway | List as INVALID conditions |
| Missing STOP command | Agents continue reading and find loopholes | Explicit STOP after action |
| No self-test section | Comprehension failures go undetected | Include quiz with answers |
| Subjective conditions | "Complex", "simple", "important" are debatable | Only boolean yes/no conditions |
Real-World Impact
Evidence from pressure testing:
- Imperative format: 33% compliance (1/3 scenarios passed)
- Same content, algorithmic format: 100% compliance (3/3 scenarios passed)
- 0% → 100% improvement from format change alone
Pressure scenarios that failed with imperatives, passed with algorithms:
- Simple tasks + 30-minute deadline → Algorithm prevented "too simple for process" rationalization
- 2 hours untested code + exhaustion + sunk cost → Algorithm mandated deletion despite investment
- Authority pressure + economic stakes → Algorithm enforced despite manager directive
Agent quotes:
"The algorithm successfully prevented me from rationalizing based on 'simple markdown edits'"
"Non-factors correctly ignored: ❌ 2 hours sunk cost, ❌ Exhaustion, ❌ Time pressure"
"The algorithmic documentation eliminated ambiguity - every condition is boolean (YES/NO)"
High-Priority Applications
Convert these workflows to algorithmic format:
- TDD enforcement - "Does code have tests? NO → Delete"
- Code review trigger - "Changes committed? YES + not reviewed? YES → Run review"
- Git workflow - Based on test status, review status
- Verification before completion - Binary checks before claiming "done"
Testing Evidence
See test artifacts for full RED-GREEN-REFACTOR campaign:
docs/tests/execute-command-test-scenarios.md- Pressure scenariosdocs/tests/execute-command-test-results.md- Baseline (RED) and imperative (GREEN) resultsdocs/tests/execute-command-algorithmic.md- Algorithmic version (REFACTOR) resultsdocs/learning/2025-10-16-algorithmic-command-enforcement.md- Complete retrospective
Methodology: Following ${CLAUDE_PLUGIN_ROOT}skills/testing-skills-with-subagents/SKILL.md - pressure scenarios with time, sunk cost, authority, and exhaustion combined.
Agent vs Command Documentation
Key distinction:
- Agents (specialized subagents): Use persuasion principles (Authority, Commitment, Scarcity, Social Proof)
- Commands (read by main Claude): Use algorithmic decision trees
Why different:
- Agents operate in closed system (dedicated to one task)
- Commands operate in open system (competing priorities)
- Agents need motivation (persuasion)
- Commands need determinism (algorithms)
Don't copy agent template principles to commands. Use appropriate format for context.
Brainstorming Ideas Into Designs
Overview
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
The Process
Understanding the idea:
- Check out the current project state first (files, docs, recent commits)
- Ask questions one at a time to refine the idea
- Prefer multiple choice questions when possible, but open-ended is fine too
- Only one question per message - if a topic needs more exploration, break it into multiple questions
- Focus on understanding: purpose, constraints, success criteria
Exploring approaches:
- Propose 2-3 different approaches with trade-offs
- Present options conversationally with your recommendation and reasoning
- Lead with your recommended option and explain why
Presenting the design:
- Once you believe you understand what you're building, present the design
- Break it into sections of 200-300 words
- Ask after each section whether it looks right so far
- Cover: architecture, components, data flow, error handling, testing
- Be ready to go back and clarify if something doesn't make sense
After the Design
Documentation:
- Write the validated design to
.work/<topic>/design.md - Use elements-of-style:writing-clearly-and-concisely skill if available
- Commit the design document to git
Implementation (if continuing):
- Ask: "Ready to set up for implementation?"
- Use cipherpowers:using-git-worktrees to create isolated workspace
- Use cipherpowers:writing-plans to create detailed implementation plan
Key Principles
- One question at a time - Don't overwhelm with multiple questions
- Multiple choice preferred - Easier to answer than open-ended when possible
- YAGNI ruthlessly - Remove unnecessary features from all designs
- Explore alternatives - Always propose 2-3 approaches before settling
- Incremental validation - Present design in sections, validate each
- Be flexible - Go back and clarify when something doesn't make sense
Capturing Learning from Completed Work
Overview
Context is lost rapidly without systematic capture. After completing work, engineers move to the next task and forget valuable lessons, discarded approaches, and subtle issues discovered. This skill provides a systematic retrospective workflow to capture learning while context is fresh.
When to Use
Use this skill when:
- Completing significant features or complex bugfixes
- After debugging sessions (especially multi-hour sessions)
- Work took longer than expected
- Multiple approaches were tried and discarded
- Subtle bugs or non-obvious issues were discovered
- Before moving to next task (capture fresh context)
- Sprint/iteration retrospectives
When NOT to use:
- Trivial changes (typo fixes, formatting)
- Work that went exactly as expected with no learnings
- When learning is already documented elsewhere
Critical Principle
Exhaustion after completion is when capture matters most.
The harder the work, the more valuable the lessons. "Too tired" means the learning is significant enough to warrant documentation.
Common Rationalizations (And Why They're Wrong)
| Rationalization | Reality |
|---|---|
| "I remember what happened" | Memory fades in days. Future you won't remember details. |
| "Too tired to write it up" | Most tired = most learning. 10 minutes now saves hours later. |
| "It's all in the commits" | Commits show WHAT changed, not WHY you chose this approach. |
| "Not worth documenting" | If you spent >30 min on it, someone else will too. Document it. |
| "It was too simple/small" | If it wasn't obvious to you at first, it won't be obvious to others. |
| "Anyone could figure this out" | You didn't know it before. Document for past-you. |
| "Nothing significant happened" | Every task teaches something. Capture incremental learning. |
| "User wants to move on" | User wants quality. Learning capture ensures it. |
None of these are valid reasons to skip capturing learning.
What to Capture
✅ MUST document:
- Brief description of what was accomplished
- Key decisions made (and why)
- Approaches that were tried and discarded (and why they didn't work)
- Non-obvious issues discovered (and how they were solved)
- Time spent vs. initial estimate (if significantly different, why?)
- Things that worked well (worth repeating)
- Things that didn't work well (worth avoiding)
- Open questions or follow-up needed
Common blind spots:
- Discarded approaches (most valuable learning often comes from what DIDN'T work)
- Subtle issues (small bugs that took disproportionate time)
- Implicit knowledge (things you learned but didn't realize were non-obvious)
Implementation
Step 1: Review the Work
Before writing, review what was done:
- Check git diff to see all changes
- Review commit messages for key decisions
- List approaches tried (including failed ones)
- Note time spent and estimates
Step 2: Capture in Structure
Create or update summary in appropriate location:
For work tracking systems:
- Use project's work directory structure
- Common:
docs/work/summary.mdor iteration-specific file
For non-tracked work:
Decide where to capture based on these criteria:
Add to CLAUDE.md/AGENTS.md when:
- Universal lesson (applies to most tasks in this repo)
- Instruction file is <200 lines (check with
wc -l) - Quick pattern/anti-pattern (1-3 lines)
- Example: "Always run tests before committing"
Create separate file docs/learning/YYYY-MM-DD-topic.md when:
- Instruction file is >200 lines (approaching limit)
- Edge case or specific scenario (not universal)
- Detailed explanation needed (>5 lines)
- Example: debugging a specific integration issue
Bloat warning: Retrospective content can quickly bloat instruction files. Prefer docs/learning/ for detailed write-ups. Only add to instruction files if the lesson is truly universal.
Before adding to instruction files:
- Check current size:
wc -l CLAUDE.md - Ask: "Will this apply to most tasks?" If no → docs/learning/
- Use
cipherpowers:maintaining-instruction-filesskill for quality verification
Minimal structure:
## [Work Item / Feature Name]
**What:** Brief description (1-2 sentences)
**Key Decisions:**
- Decision 1 (why)
- Decision 2 (why)
**What Didn't Work:**
- Approach X (why it failed, what we learned)
- Approach Y (why it failed)
**Issues Discovered:**
- Issue 1 (how solved)
- Issue 2 (how solved)
**Time Notes:**
Estimated X hours, took Y hours. [Explain if significant difference]
**Open Questions:**
- Question 1
- Question 2
Step 3: Link to Implementation
Connect learning to codebase:
- Reference key files modified
- Link to commits or PRs
- Cross-reference to CLAUDE.md if patterns emerged
Step 4: Make it Searchable
Ensure future discoverability:
- Use descriptive headings
- Include error messages if debugging
- Tag with relevant technology/pattern names
Real-World Impact
Without systematic capture:
- Repeat same failed approaches (waste time)
- Forget subtle issues (encounter again later)
- Lose context on decisions (question past choices)
- Can't transfer knowledge to team
- Learning stays with individual
With this workflow:
- Failed approaches documented (others avoid same path)
- Subtle issues captured (searchable solutions)
- Decision rationale preserved (future maintenance easier)
- Knowledge shared across team
- Organization builds learning repository
Integration with Commands/Agents
This skill can be invoked by:
/cipherpowers:summarisecommand for retrospective capture- Pre-merge checklist item
- Sprint/iteration retrospective workflows
- Code review requirements
Commands should provide context about where to save summaries and reference this skill for methodology.
Commit Workflow
Overview
Structured commit process ensuring code quality through pre-commit verification, atomic commit composition, and conventional commit message formatting.
Quick Reference
Before committing:
- Check staging status
- Review diff to understand changes
- Analyze for atomic commit opportunities
Commit composition:
- Split multiple distinct changes into separate commits
- Use conventional commit format
- Follow project git guidelines
Note: Quality gates (PostToolUse, SubagentStop hooks) automatically enforce pre-commit checks, so code quality is already verified.
Implementation
Prerequisites
Read these before committing:
${CLAUDE_PLUGIN_ROOT}standards/conventional-commits.md- Commit message format${CLAUDE_PLUGIN_ROOT}standards/git-guidelines.md- Git workflow standards
Step-by-Step Workflow
Note: Pre-commit quality checks (linters, tests, build) are enforced automatically by quality gates (PostToolUse, SubagentStop hooks). By the time you're committing, gates have already verified code quality.
1. Check staging status
Review what's staged:
git status
If 0 files staged:
- Automatically add all modified and new files:
git add . - Or selectively stage:
git add <specific-files>
2. Review diff
Understand what's being committed:
# See staged changes
git diff --staged
# See all changes (staged + unstaged)
git diff HEAD
Analyze for logical grouping:
- Are multiple distinct features/fixes present?
- Can this be split into atomic commits?
3. Determine commit strategy
Single commit: All changes are logically related (one feature, one fix)
Multiple commits: Multiple distinct changes detected:
- Feature A + Bug fix B → Split into 2 commits
- Refactoring + New feature → Split into 2 commits
- Multiple unrelated changes → Split into N commits
If splitting, stage selectively:
# Stage specific files
git add file1.py file2.py
git commit -m "..."
# Stage remaining files
git add file3.py
git commit -m "..."
4. Write conventional commit message
Format (from standards/conventional-commits.md):
<type>(<optional-scope>): <description>
[optional body]
[optional footer]
Common types:
feat: New featurefix: Bug fixrefactor: Code change that neither fixes bug nor adds featuredocs: Documentation changestest: Adding or updating testschore: Maintenance tasks
Example messages:
git commit -m "feat(auth): add password reset functionality
Implement forgot-password flow with email verification.
Includes rate limiting to prevent abuse."
git commit -m "fix: handle null values in user profile endpoint"
git commit -m "refactor: extract validation logic into separate module
Improves testability and reduces duplication across endpoints."
5. Commit changes
Execute commit:
git commit -m "type(scope): description"
Verify commit:
git log -1 --stat
What NOT to Skip
NEVER skip:
- Reviewing full diff before committing
- Analyzing for atomic commit opportunities
- Following conventional commit format
- Verifying commit was created correctly
Common rationalizations that violate workflow:
- "Small change" → Review diff and follow format anyway
- "Will fix message later" → Write correct message now
- "Mixing changes is faster" → Atomic commits are worth the time
- "Don't need to verify" → Always check commit with git log
Note: Pre-commit quality checks are enforced by quality gates automatically - no need to run them manually at commit time.
Testing This Skill
See test-scenarios.md for pressure tests validating this workflow resists shortcuts.
Condition-Based Waiting
Overview
Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
Core principle: Wait for the actual condition you care about, not a guess about how long it takes.
When to Use
digraph when_to_use {
"Test uses setTimeout/sleep?" [shape=diamond];
"Testing timing behavior?" [shape=diamond];
"Document WHY timeout needed" [shape=box];
"Use condition-based waiting" [shape=box];
"Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
"Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
"Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
}
Use when:
- Tests have arbitrary delays (
setTimeout,sleep,time.sleep()) - Tests are flaky (pass sometimes, fail under load)
- Tests timeout when run in parallel
- Waiting for async operations to complete
Don't use when:
- Testing actual timing behavior (debounce, throttle intervals)
- Always document WHY if using arbitrary timeout
Core Pattern
// ❌ BEFORE: Guessing at timing
await new Promise(r => setTimeout(r, 50));
const result = getResult();
expect(result).toBeDefined();
// ✅ AFTER: Waiting for condition
await waitFor(() => getResult() !== undefined);
const result = getResult();
expect(result).toBeDefined();
Quick Patterns
| Scenario | Pattern |
|---|---|
| Wait for event | waitFor(() => events.find(e => e.type === 'DONE')) |
| Wait for state | waitFor(() => machine.state === 'ready') |
| Wait for count | waitFor(() => items.length >= 5) |
| Wait for file | waitFor(() => fs.existsSync(path)) |
| Complex condition | waitFor(() => obj.ready && obj.value > 10) |
Implementation
Generic polling function:
async function waitFor<T>(
condition: () => T | undefined | null | false,
description: string,
timeoutMs = 5000
): Promise<T> {
const startTime = Date.now();
while (true) {
const result = condition();
if (result) return result;
if (Date.now() - startTime > timeoutMs) {
throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
}
await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
}
}
See @example.ts for complete implementation with domain-specific helpers (waitForEvent, waitForEventCount, waitForEventMatch) from actual debugging session.
Common Mistakes
❌ Polling too fast: setTimeout(check, 1) - wastes CPU
✅ Fix: Poll every 10ms
❌ No timeout: Loop forever if condition never met ✅ Fix: Always include timeout with clear error
❌ Stale data: Cache state before loop ✅ Fix: Call getter inside loop for fresh data
When Arbitrary Timeout IS Correct
// Tool ticks every 100ms - need 2 ticks to verify partial output
await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
await new Promise(r => setTimeout(r, 200)); // Then: wait for timed behavior
// 200ms = 2 ticks at 100ms intervals - documented and justified
Requirements:
- First wait for triggering condition
- Based on known timing (not guessing)
- Comment explaining WHY
Real-World Impact
From debugging session (2025-10-03):
- Fixed 15 flaky tests across 3 files
- Pass rate: 60% → 100%
- Execution time: 40% faster
- No more race conditions
Conducting Code Review
Overview
Systematic code review process ensuring correctness, security, and maintainability through practice adherence and structured feedback. Tests and checks are assumed to pass - reviewer focuses on code quality.
Quick Reference
Before starting:
- Read upstream skill:
${CLAUDE_PLUGIN_ROOT}skills/requesting-code-review/SKILL.md - Read project practices:
${CLAUDE_PLUGIN_ROOT}standards/code-review.md
Core workflow:
- Review most recent commit(s)
- Review against practice standards (all severity levels)
- Save structured feedback to work directory
Note: Tests and checks are assumed to pass. Focus on code quality review.
Implementation
Prerequisites
Read these before conducting review:
${CLAUDE_PLUGIN_ROOT}skills/requesting-code-review/SKILL.md- Understand requester expectations${CLAUDE_PLUGIN_ROOT}standards/code-review.md- Standards, severity levels, project commands
Step-by-Step Workflow
1. Identify code to review
Determine scope:
- Most recent commit:
git log -1 --stat - Recent commits on branch:
git log origin/main..HEAD - Full diff:
git diff origin/main...HEAD
2. Review code against standards
Read standards from practices:
# Standards live in practices, not in this skill
${CLAUDE_PLUGIN_ROOT}standards/code-review.md
Review ALL severity levels:
- BLOCKING (Must Fix Before Merge) - from practices
- NON-BLOCKING (Can Be Deferred) - from practices
Empty sections are GOOD if you actually checked. Missing sections mean you didn't check.
3. Save structured review - ALGORITHMIC ENFORCEMENT
Template location:
${CLAUDE_PLUGIN_ROOT}templates/code-review-template.md
Template Validation Algorithm
1. Check Status section exists
Does your review have ## Status: [BLOCKED | APPROVED WITH SUGGESTIONS | APPROVED]?
- NO → STOP. Delete draft. Start over with template.
- YES → CONTINUE
2. Check BLOCKING section exists
Does your review have ## BLOCKING (Must Fix Before Merge)?
- NO → STOP. Delete draft. Start over with template.
- YES → CONTINUE
3. Check NON-BLOCKING section exists
Does your review have ## NON-BLOCKING (May Be Deferred)?
- NO → STOP. Delete draft. Start over with template.
- YES → CONTINUE
4. Check Checklist section exists
Does your review have ## Checklist with all 6 categories?
- NO → STOP. Delete draft. Start over with template.
- YES → CONTINUE
5. Check for prohibited custom sections
Have you added ANY sections not listed above (examples of PROHIBITED sections: Strengths, Code Quality Metrics, Assessment, Recommendations, Requirements Verification, Comparison to Previous Reviews, Reviewer Notes, Sign-Off, Review Summary, Issues with subsections, Test Results, Check Results, Next Steps)?
- YES → STOP. Delete custom sections. Use template exactly.
- NO → CONTINUE
6. Save review file
All required sections present, no custom sections → Save to work directory.
File naming: See ${CLAUDE_PLUGIN_ROOT}standards/code-review.md for .work directory location and naming convention ({YYYY-MM-DD}-review-{N}.md).
Additional context allowed: You may add supplementary details AFTER the Checklist section (verification commands run, files changed, commit hashes). But the 4 required sections above are mandatory and must appear first in the exact order shown.
What NOT to Skip
NEVER skip:
- Reviewing ALL severity levels (not just critical)
- Saving review file to work directory
- Including positive observations
Common rationalizations that violate workflow:
- "Code looks clean" → Check all severity levels anyway
- "Simple change" → Thorough review prevents production bugs
- "Senior developer" → Review objectively regardless of author
- "Template is too simple, adding sections" → Step 3 algorithm checks for custom sections. STOP if they exist.
- "My format is more thorough" → Thoroughness goes IN the template sections. Algorithm enforces exact structure.
- "Adding Strengths section helps" → PROHIBITED. Algorithm Step 6 blocks this.
- "Assessment section adds value" → PROHIBITED. Algorithm Step 6 blocks this.
- "Requirements Verification is useful" → Put in NON-BLOCKING or Checklist. Not a separate section.
Note: Tests and checks are assumed to pass. Reviewers focus on code quality, not test execution.
Related Skills
Requestion code review:
- Requesting Code Review:
${CLAUDE_PLUGIN_ROOT}skills/requesting-code-review/SKILL.md
When receiving feedback on your review:
- Code Review Reception:
${CLAUDE_PLUGIN_ROOT}skills/receiving-code-review/SKILL.md
Testing This Skill
See test-scenarios.md for pressure tests validating this workflow resists rationalization.
Creating Research Packages
Overview
Bundle complex domain knowledge into self-contained modules with multiple entry points for different time budgets and reader roles.
Announce at start: "I'm using the creating-research-packages skill to document this domain knowledge."
When to Use
- Documenting complex research findings
- Creating domain knowledge packages (physics, algorithms, APIs)
- Building self-contained documentation that can be shared independently
- Topics requiring multiple reading paths (quick overview vs deep dive)
- Knowledge that needs verification tracking
The Process
Step 1: Identify the Package Scope
Determine what knowledge should be packaged:
- What is the core topic?
- What are the sub-topics?
- Who are the readers? (roles, time budgets)
- What verification is needed?
Step 2: Create Directory Structure
mkdir -p docs/[topic]
Standard package structure:
[topic]/
├── 00-START-HERE.md # Entry point + verification status
├── README.md # Package overview + TL;DR
├── how-to-use-this.md # Detailed navigation guide
├── [core-topic-1].md # Main research content
├── [core-topic-2].md # Additional research
├── design-decisions.md # Why decisions were made
├── QUICK-REFERENCE.md # One-page summary
├── VERIFICATION-REVIEW.md # Accuracy audit
└── examples/ # Working examples (if applicable)
Step 3: Write Entry Point (00-START-HERE.md)
Include:
- Verification status with visual indicators
- Time budget options (5 min, 20 min, 2 hours)
- Quick navigation to key documents
- Prerequisites if any
# [Topic]: Start Here
**Status:** ✅ Verified | **Last Updated:** YYYY-MM-DD
## Choose Your Path
| Time | Goal | Start With |
|------|------|------------|
| 5 min | Quick overview | [TL;DR section in README] |
| 20 min | Understand context | [README + design-decisions] |
| 2 hours | Full understanding | [All documents in sequence] |
Step 4: Write README with TL;DR
The README is the package overview:
- TL;DR section (2-3 sentences, the essential insight)
- Reading paths by time budget
- Role-based paths
- Package contents overview
- Key concepts with links to details
Use template: ${CLAUDE_PLUGIN_ROOT}templates/research-package-template.md
Step 5: Write Navigation Guide (how-to-use-this.md)
Detailed guide for different readers:
- Role-based paths with reading orders
- Time estimates for each path
- Key takeaways for each role
- Cross-references between documents
Step 6: Write Core Content
For each topic document:
- Clear scope statement
- Structured content with headers
- Visual aids where helpful (diagrams, tables)
- Cross-references to related docs
- Verification notes if applicable
Step 7: Create Quick Reference
One-page summary for rapid lookup:
- Key formulas/constants
- Common commands
- Quick diagnosis table
- Status icons legend
Use template: ${CLAUDE_PLUGIN_ROOT}templates/quick-reference-template.md
Step 8: Add Verification Tracking
If accuracy is critical:
- Create VERIFICATION-REVIEW.md
- Track what was verified and when
- Note discrepancies found
- Link to authoritative sources
- Include recommended updates
Step 9: Verify Package Completeness
Checklist:
- 00-START-HERE.md has clear navigation
- README has TL;DR that captures essence
- Reading paths cover different time budgets
- Role-based paths for different readers
- QUICK-REFERENCE is truly one page
- All cross-references work
- Verification status current
Checklist
- Package scope clearly defined
- Directory structure created
- Entry point (00-START-HERE) written
- README with TL;DR written
- Navigation guide written
- Core content documents written
- Quick reference created
- Verification tracking if needed
- All internal links verified
Anti-Patterns
Don't:
- Create packages for simple topics (overkill)
- Skip the TL;DR (readers need quick overview)
- Omit time estimates (readers can't plan)
- Ignore verification for critical knowledge
- Make QUICK-REFERENCE more than one page
Do:
- Keep TL;DR to 2-3 sentences
- Provide multiple entry points
- Track verification for technical accuracy
- Cross-reference liberally
- Test navigation with fresh eyes
Related Skills
- Organizing documentation:
${CLAUDE_PLUGIN_ROOT}skills/organizing-documentation/SKILL.md - Documenting debugging workflows:
${CLAUDE_PLUGIN_ROOT}skills/documenting-debugging-workflows/SKILL.md - Creating quality gates:
${CLAUDE_PLUGIN_ROOT}skills/creating-quality-gates/SKILL.md
References
- Standards:
${CLAUDE_PLUGIN_ROOT}standards/documentation-structure.md - Template:
${CLAUDE_PLUGIN_ROOT}templates/research-package-template.md - Quick Reference Template:
${CLAUDE_PLUGIN_ROOT}templates/quick-reference-template.md
Defense-in-Depth Validation
Overview
When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
Core principle: Validate at EVERY layer data passes through. Make the bug structurally impossible.
Why Multiple Layers
Single validation: "We fixed the bug" Multiple layers: "We made the bug impossible"
Different layers catch different cases:
- Entry validation catches most bugs
- Business logic catches edge cases
- Environment guards prevent context-specific dangers
- Debug logging helps when other layers fail
The Four Layers
Layer 1: Entry Point Validation
Purpose: Reject obviously invalid input at API boundary
function createProject(name: string, workingDirectory: string) {
if (!workingDirectory || workingDirectory.trim() === '') {
throw new Error('workingDirectory cannot be empty');
}
if (!existsSync(workingDirectory)) {
throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
}
if (!statSync(workingDirectory).isDirectory()) {
throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
}
// ... proceed
}
Layer 2: Business Logic Validation
Purpose: Ensure data makes sense for this operation
function initializeWorkspace(projectDir: string, sessionId: string) {
if (!projectDir) {
throw new Error('projectDir required for workspace initialization');
}
// ... proceed
}
Layer 3: Environment Guards
Purpose: Prevent dangerous operations in specific contexts
async function gitInit(directory: string) {
// In tests, refuse git init outside temp directories
if (process.env.NODE_ENV === 'test') {
const normalized = normalize(resolve(directory));
const tmpDir = normalize(resolve(tmpdir()));
if (!normalized.startsWith(tmpDir)) {
throw new Error(
`Refusing git init outside temp dir during tests: ${directory}`
);
}
}
// ... proceed
}
Layer 4: Debug Instrumentation
Purpose: Capture context for forensics
async function gitInit(directory: string) {
const stack = new Error().stack;
logger.debug('About to git init', {
directory,
cwd: process.cwd(),
stack,
});
// ... proceed
}
Applying the Pattern
When you find a bug:
- Trace the data flow - Where does bad value originate? Where used?
- Map all checkpoints - List every point data passes through
- Add validation at each layer - Entry, business, environment, debug
- Test each layer - Try to bypass layer 1, verify layer 2 catches it
Example from Session
Bug: Empty projectDir caused git init in source code
Data flow:
- Test setup → empty string
Project.create(name, '')WorkspaceManager.createWorkspace('')git initruns inprocess.cwd()
Four layers added:
- Layer 1:
Project.create()validates not empty/exists/writable - Layer 2:
WorkspaceManagervalidates projectDir not empty - Layer 3:
WorktreeManagerrefuses git init outside tmpdir in tests - Layer 4: Stack trace logging before git init
Result: All 1847 tests passed, bug impossible to reproduce
Key Insight
All four layers were necessary. During testing, each layer caught bugs the others missed:
- Different code paths bypassed entry validation
- Mocks bypassed business logic checks
- Edge cases on different platforms needed environment guards
- Debug logging identified structural misuse
Don't stop at one validation point. Add checks at every layer.
Dispatching Parallel Agents
Overview
When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
Core principle: Dispatch one agent per independent problem domain. Let them work concurrently.
When to Use
digraph when_to_use {
"Multiple failures?" [shape=diamond];
"Are they independent?" [shape=diamond];
"Single agent investigates all" [shape=box];
"One agent per problem domain" [shape=box];
"Can they work in parallel?" [shape=diamond];
"Sequential agents" [shape=box];
"Parallel dispatch" [shape=box];
"Multiple failures?" -> "Are they independent?" [label="yes"];
"Are they independent?" -> "Single agent investigates all" [label="no - related"];
"Are they independent?" -> "Can they work in parallel?" [label="yes"];
"Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
"Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}
Use when:
- 3+ test files failing with different root causes
- Multiple subsystems broken independently
- Each problem can be understood without context from others
- No shared state between investigations
Don't use when:
- Failures are related (fix one might fix others)
- Need to understand full system state
- Agents would interfere with each other
The Pattern
1. Identify Independent Domains
Group failures by what's broken:
- File A tests: Tool approval flow
- File B tests: Batch completion behavior
- File C tests: Abort functionality
Each domain is independent - fixing tool approval doesn't affect abort tests.
2. Create Focused Agent Tasks
Each agent gets:
- Specific scope: One test file or subsystem
- Clear goal: Make these tests pass
- Constraints: Don't change other code
- Expected output: Summary of what you found and fixed
3. Dispatch in Parallel
// In Claude Code / AI environment
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
Task("Fix tool-approval-race-conditions.test.ts failures")
// All three run concurrently
4. Review and Integrate
When agents return:
- Read each summary
- Verify fixes don't conflict
- Run project test command
- Integrate all changes
Agent Prompt Structure
Good agent prompts are:
- Focused - One clear problem domain
- Self-contained - All context needed to understand the problem
- Specific about output - What should the agent return?
Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0
These are timing/race condition issues. Your task:
1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
- Replacing arbitrary timeouts with event-based waiting
- Fixing bugs in abort implementation if found
- Adjusting test expectations if testing changed behavior
Do NOT just increase timeouts - find the real issue.
Return: Summary of what you found and what you fixed.
Common Mistakes
❌ Too broad: "Fix all the tests" - agent gets lost ✅ Specific: "Fix agent-tool-abort.test.ts" - focused scope
❌ No context: "Fix the race condition" - agent doesn't know where ✅ Context: Paste the error messages and test names
❌ No constraints: Agent might refactor everything ✅ Constraints: "Do NOT change production code" or "Fix tests only"
❌ Vague output: "Fix it" - you don't know what changed ✅ Specific: "Return summary of root cause and changes"
When NOT to Use
Related failures: Fixing one might fix others - investigate together first Need full context: Understanding requires seeing entire system Exploratory debugging: You don't know what's broken yet Shared state: Agents would interfere (editing same files, using same resources)
Real Example from Session
Scenario: 6 test failures across 3 files after major refactoring
Failures:
- agent-tool-abort.test.ts: 3 failures (timing issues)
- batch-completion-behavior.test.ts: 2 failures (tools not executing)
- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
Decision: Independent domains - abort logic separate from batch completion separate from race conditions
Dispatch:
Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts
Results:
- Agent 1: Replaced timeouts with event-based waiting
- Agent 2: Fixed event structure bug (threadId in wrong place)
- Agent 3: Added wait for async tool execution to complete
Integration: All fixes independent, no conflicts, full suite green
Time saved: 3 problems solved in parallel vs sequentially
Key Benefits
- Parallelization - Multiple investigations happen simultaneously
- Focus - Each agent has narrow scope, less context to track
- Independence - Agents don't interfere with each other
- Speed - 3 problems solved in time of 1
Verification
After agents return:
- Review each summary - Understand what changed
- Check for conflicts - Did agents edit same code?
- Run full suite - Verify all fixes work together
- Spot check - Agents can make systematic errors
Real-World Impact
From debugging session (2025-10-03):
- 6 failures across 3 files
- 3 agents dispatched in parallel
- All investigations completed concurrently
- All fixes integrated successfully
- Zero conflicts between agent changes
Documenting Debugging Workflows
Overview
Create debugging documentation organized by observable symptoms, not root causes. Developers search by what they see, not by what's wrong.
Announce at start: "I'm using the documenting-debugging-workflows skill to create symptom-based debugging docs."
When to Use
- Creating debugging documentation for a project
- Documenting common bugs and their fixes
- Building troubleshooting guides
- Organizing FIX/ section content
- Recurring issues need documentation
Core Principle
Wrong: Organize by root cause (memory-leaks/, type-errors/) Right: Organize by observable symptom (visual-bugs/, slow-startup/)
Developers don't know the root cause when they start debugging - they know what they observe.
The Process
Step 1: Collect Symptoms
Gather observable symptoms from:
- Bug reports and issues
- Support tickets
- Slack/team chat questions
- Your own debugging sessions
- Code review comments
For each symptom, note:
- What exactly does the developer see?
- How do they describe it?
- What words do they use to search?
Step 2: Create Symptom Categories
Group symptoms by observable category:
FIX/
├── symptoms/
│ ├── visual-bugs/ # "Rendering looks wrong"
│ ├── performance/ # "It's slow"
│ ├── test-failures/ # "Tests fail"
│ ├── build-errors/ # "Won't compile"
│ └── data-issues/ # "Data is wrong"
├── investigation/
│ └── systematic-debugging.md
└── solutions/
└── common-fixes.md
Choose categories based on YOUR project's common issues.
Step 3: Build Quick Diagnosis Table
Create the entry point with a scannable table:
# [Category] Debugging Guide
## Quick Diagnosis
| Symptom | Likely Cause | Investigation | Priority |
|---------|--------------|---------------|----------|
| [What you see] | [Root cause] | [Link] | ⚠️ High |
| [What you see] | [Root cause] | [Link] | ☠️ Critical |
Priority icons:
- ☠️ Critical (production impact)
- ⚠️ High (blocking work)
- 🎯 Medium (should fix soon)
- ✅ Low (minor annoyance)
Step 4: Document Each Symptom
For each symptom, create structured documentation:
- What You See - Exact observable behavior
- Likely Causes - Ordered by probability
- Investigation Steps - With commands to run
- Solutions - Fixes for each cause
- Prevention - How to avoid in future
Use template: ${CLAUDE_PLUGIN_ROOT}templates/symptom-debugging-template.md
Step 5: Create Investigation Strategies
Document systematic approaches in investigation/:
- How to reproduce consistently
- How to isolate the problem
- Gathering evidence (logs, metrics)
- Forming and testing hypotheses
- Binary search for breaking changes
Step 6: Build Solutions Catalog
Document known fixes in solutions/:
- Common error codes and fixes
- Proven workarounds
- Configuration fixes
- Code patterns that prevent issues
Step 7: Add Escalation Guidance
Document when to escalate:
- Time thresholds (stuck > X hours)
- Impact thresholds (production, data, security)
- Who to contact
- What information to gather first
Step 8: Verify and Maintain
- Test documentation with someone unfamiliar
- Update when new symptoms discovered
- Archive outdated fixes (don't delete - mark as historical)
- Track which docs get used most
Checklist
- Symptoms collected from real sources
- Categories match project's common issues
- Quick diagnosis table created
- Each symptom has structured documentation
- Investigation strategies documented
- Solutions catalog started
- Escalation guidance clear
- Tested with fresh eyes
Anti-Patterns
Don't:
- Organize by root cause (developers don't know it yet)
- Skip the quick diagnosis table
- Write investigation steps without commands
- Forget escalation guidance
- Let docs become stale
Do:
- Use exact symptom descriptions
- Include runnable commands
- Link to related docs liberally
- Update when fixes are found
- Track which docs help most
Example: Visual Bug Entry
## Rendering Artifacts on Screen
### What You See
Flickering textures, z-fighting, or objects appearing through walls.
### Likely Causes
1. **Floating point precision** (most common)
- Objects far from origin
- Verify: Check object world coordinates
2. **Z-buffer precision**
- Near/far plane ratio too large
- Verify: Check camera settings
### Investigation Steps
1. [ ] Log object world coordinates
```rust
info!("Position: {:?}", transform.translation);
If > 10000 units from origin → floating point issue
- Check camera near/far planes
If ratio > 10000 → z-buffer issueinfo!("Near: {}, Far: {}", camera.near, camera.far);
Solutions
If floating point: Implement floating origin If z-buffer: Adjust camera planes
Prevention
- Use floating origin for large worlds
- Keep near plane as far as acceptable
## Related Skills
- **Organizing documentation:** `${CLAUDE_PLUGIN_ROOT}skills/organizing-documentation/SKILL.md`
- **Creating research packages:** `${CLAUDE_PLUGIN_ROOT}skills/creating-research-packages/SKILL.md`
- **Creating quality gates:** `${CLAUDE_PLUGIN_ROOT}skills/creating-quality-gates/SKILL.md`
## References
- Standards: `${CLAUDE_PLUGIN_ROOT}standards/documentation-structure.md`
- Template: `${CLAUDE_PLUGIN_ROOT}templates/symptom-debugging-template.md`
Dual Verification Review
Overview
Use two independent agents to systematically review content or research a topic, then use a collation agent to compare findings.
Core principle: Independent dual perspective + systematic collation = higher quality, managed context.
Announce at start: "I'm using the dual-verification skill for comprehensive [review/research]."
When to Use
Use dual-verification when:
For Reviews:
- High-stakes decisions: Before executing implementation plans, merging to production, or deploying
- Comprehensive audits: Documentation accuracy, plan quality, code correctness
- Quality assurance: Critical content that must be verified against ground truth
- Risk mitigation: When cost of missing issues exceeds cost of dual review
For Research:
- Codebase exploration: Understanding unfamiliar code from multiple angles
- Problem investigation: Exploring a bug or issue with different hypotheses
- Information gathering: Researching a topic where completeness matters
- Architecture analysis: Understanding system design from different perspectives
- Building confidence: When you need high-confidence understanding before proceeding
Don't use when:
- Simple, low-stakes changes (typo fixes, minor documentation tweaks)
- Time-critical situations (production incidents requiring immediate action)
- Single perspective is sufficient (trivial updates, following up on previous review)
- Cost outweighs benefit (quick questions with obvious answers)
Quick Reference
| Phase | Action | Output | User Action |
|---|---|---|---|
| Phase 1 | Dispatch 2 agents in parallel | Two independent reports | Wait |
| Phase 2 | Collate findings, present to user | Collated report | Can /revise common |
| Phase 3 | Cross-check exclusive issues (background) | Validated exclusive issues | Can /revise exclusive or /revise all |
Confidence levels:
- VERY HIGH: Both agents found (high confidence - act on this)
- MODERATE: One agent found (unique insight - needs cross-check)
- INVESTIGATE: Agents disagree (resolved during collation)
Exclusive issue states (after cross-check):
- VALIDATED: Cross-check confirmed issue exists → implement
- INVALIDATED: Cross-check found issue doesn't apply → skip
- UNCERTAIN: Cross-check couldn't determine → user decides
Why This Pattern Works
Higher quality through independence:
- Common findings = high confidence (both found)
- Exclusive findings = unique insights one agent caught → validated by cross-check
- Divergences = resolved during collation
Context management:
- Two detailed reviews = lots of context
- Collation agent does comparison work
- Cross-check runs in background while user reviews
- Main context gets clean summary
Confidence progression:
- Both found → VERY HIGH → Fix immediately (
/revise common) - One found → MODERATE → Cross-check validates → VALIDATED/INVALIDATED/UNCERTAIN
- Disagree → INVESTIGATE → Resolved during collation
Parallel workflow:
- User gets collation results immediately
- Can start
/revise commonwhile cross-check runs - Cross-check completes →
/revise exclusiveor/revise all
The Three-Phase Process
Phase 1: Dual Independent Review
Dispatch 2 agents in parallel with identical prompts.
Agent prompt template:
You are [agent type] conducting an independent verification review.
**Context:** You are one of two agents performing parallel independent reviews. Another agent is reviewing the same content independently. A collation agent will later compare both reviews.
**Your task:** Systematically verify [subject] against [ground truth].
**Critical instructions:**
- Current content CANNOT be assumed correct. Verify every claim.
- You MUST follow the review report template structure
- Template location: ${CLAUDE_PLUGIN_ROOT}templates/verify-template.md
- You MUST save your review with timestamp: `.work/{YYYY-MM-DD}-verify-{type}-{HHmmss}.md`
- Time-based naming prevents conflicts when agents run in parallel.
- Work completely independently - the collation agent will find and compare all reviews.
**Process:**
1. Read the review report template to understand the expected structure
2. Read [subject] completely
3. For each [section/component/claim]:
- Identify what is claimed
- Verify against [ground truth]
- Check for [specific criteria]
4. Categorize issues by:
- Category ([issue type 1], [issue type 2], etc.)
- Location (file/section/line)
- Severity ([severity levels])
5. For each issue, provide:
- Current content (what [subject] says)
- Actual [ground truth] (what is true)
- Impact (why this matters)
- Action (specific recommendation)
6. Save using template structure with all required sections
**The template provides:**
- Complete structure for metadata, issues, summary, assessment
- Examples of well-written reviews
- Guidance on severity levels and categorization
Example: Documentation Review
- Agent type: technical-writer
- Subject: README.md and CLAUDE.md
- Ground truth: current codebase implementation
- Criteria: file paths exist, commands work, examples accurate
Example: Plan Review
- Agent type: plan-review-agent
- Subject: implementation plan
- Ground truth: 35 quality criteria (security, testing, architecture, etc.)
- Criteria: blocking issues, non-blocking improvements
Example: Code Review
- Agent type: code-review-agent
- Subject: implementation code
- Ground truth: coding standards, plan requirements
- Criteria: meets requirements, follows standards, has tests
Phase 2: Collate Findings and Present
Dispatch collation agent to compare the two reviews, then present to user immediately.
Dispatch collation agent:
Use Task tool with:
subagent_type: "cipherpowers:review-collation-agent"
description: "Collate dual [review type] reviews"
prompt: "You are collating two independent [review type] reviews.
**Critical instructions:**
- You MUST follow the collation report template structure
- Template location: ${CLAUDE_PLUGIN_ROOT}templates/verify-collation-template.md
- Read the template BEFORE starting collation
- Save to: `.work/{YYYY-MM-DD}-verify-{type}-collated-{HHmmss}.md`
**Inputs:**
- Review #1: [path to first review file]
- Review #2: [path to second review file]
**Your task:**
1. **Read the collation template** to understand the required structure
2. **Parse both reviews completely:**
- Extract all issues from Review #1
- Extract all issues from Review #2
- Create internal comparison matrix
3. **Identify common issues** (both found):
- Same issue found by both reviewers
- Confidence: VERY HIGH
4. **Identify exclusive issues** (only one found):
- Issues found only by Agent #1
- Issues found only by Agent #2
- Confidence: MODERATE (pending cross-check)
5. **Identify divergences** (agents disagree):
- Same location, different conclusions
- Contradictory findings
6. **IF divergences exist → Verify with appropriate agent:**
- Dispatch verification agent for each divergence
- Provide both perspectives and specific divergence point
- Incorporate verification analysis into report
7. **Follow template structure for output:**
- Metadata section (complete all fields)
- Executive summary (totals and breakdown)
- Common issues (VERY HIGH confidence)
- Exclusive issues (MODERATE confidence - pending cross-check)
- Divergences (with verification analysis)
- Recommendations (categorized by action type)
- Overall assessment
**The template provides:**
- Complete structure with all required sections
- Examples of well-written collation reports
- Guidance on confidence levels and categorization
- Usage notes for proper assessment
Present collated report to user immediately:
Collation complete. Report saved to: [path]
**Summary:**
- Common issues: X (VERY HIGH confidence) → Can `/revise common` now
- Exclusive issues: X (MODERATE - cross-check starting)
- Divergences: X (resolved/unresolved)
**Status:** Cross-check running in background...
User can now /revise common while cross-check runs.
Phase 3: Cross-check Exclusive Issues
Dispatch cross-check agent to validate exclusive issues against the codebase/implementation.
This phase runs in the background after presenting collation to user.
Purpose: Exclusive issues have MODERATE confidence because only one reviewer found them. Cross-check validates whether the issue actually exists by checking against ground truth.
Dispatch cross-check agent:
Use Task tool with:
subagent_type: "[appropriate agent for review type]"
description: "Cross-check exclusive issues"
prompt: "You are cross-checking exclusive issues from a dual-verification review.
**Context:**
Two independent reviewers performed a [review type] review. The collation identified
issues found by only one reviewer (exclusive issues). Your task is to validate
whether each exclusive issue actually exists.
**Collation report:** [path to collation file]
**Your task:**
For EACH exclusive issue in the collation report:
1. **Read the issue description** from the collation report
2. **Verify against ground truth:**
- For doc reviews: Check if the claim is accurate against codebase
- For code reviews: Check if the issue exists in the implementation
- For plan reviews: Check if the concern is valid against requirements
3. **Assign validation status:**
- VALIDATED: Issue confirmed to exist → should be addressed
- INVALIDATED: Issue does not apply → can be skipped
- UNCERTAIN: Cannot determine → escalate to user
**Output format:**
For each exclusive issue, provide:
- Issue: [from collation]
- Source: Reviewer #[1/2]
- Validation: [VALIDATED/INVALIDATED/UNCERTAIN]
- Evidence: [what you found that supports your conclusion]
- Recommendation: [action to take]
**Save to:** `.work/{YYYY-MM-DD}-verify-{type}-crosscheck-{HHmmss}.md`
Agent selection for cross-check:
| Review Type | Cross-check Agent |
|---|---|
| docs | cipherpowers:code-agent (verify against implementation) |
| code | cipherpowers:code-agent (verify against codebase) |
| plan | cipherpowers:plan-review-agent (verify against requirements) |
| execute | cipherpowers:execute-review-agent (verify against plan) |
When cross-check completes:
Cross-check complete. Report saved to: [path]
**Exclusive Issues Status:**
- VALIDATED: X issues (confirmed, should address)
- INVALIDATED: X issues (can skip)
- UNCERTAIN: X issues (user decides)
**Ready for:** `/cipherpowers:revise exclusive` or `/cipherpowers:revise all`
Update collation report with cross-check results:
- Read original collation file
- Update exclusive issues section with validation status
- Save updated collation (overwrite or append cross-check section)
Parameterization
Make the pattern flexible by specifying:
Subject: What to review
- Documentation files (README.md, CLAUDE.md)
- Implementation plans (plan.md)
- Code changes (git diff, specific files)
- Test coverage (test files)
- Architecture decisions (design docs)
Ground truth: What to verify against
- Current implementation (codebase)
- Quality criteria (35-point checklist)
- Coding standards (practices)
- Requirements (specifications)
- Design documents (architecture)
Agent type: Which specialized agent to use
- technical-writer (documentation)
- plan-review-agent (plans)
- code-review-agent (code)
- rust-agent (Rust-specific)
- ultrathink-debugger (complex issues)
Granularity: How to break down review
- Section-by-section (documentation)
- Criteria-by-criteria (plan review)
- File-by-file (code review)
- Feature-by-feature (architecture review)
Severity levels: How to categorize issues
- critical/high/medium/low (general)
- BLOCKING/NON-BLOCKING (plan/code review)
- security/performance/maintainability (code review)
When NOT to Use
Skip dual verification when:
- Simple, low-stakes changes (typo fixes)
- Time-critical situations (production incidents)
- Single perspective sufficient (trivial updates)
- Cost outweighs benefit (minor documentation tweaks)
Use single agent when:
- Regular incremental updates
- Following up on dual review findings
- Implementing approved changes
Example Usage: Plan Review
User: Review this implementation plan before execution
You: I'm using the dual-verification skill for comprehensive review.
Phase 1: Dual Independent Review
→ Dispatch 2 plan-review-agent agents in parallel
→ Each applies 35 quality criteria independently
→ Agent #1 finds: 3 BLOCKING issues, 7 NON-BLOCKING
→ Agent #2 finds: 4 BLOCKING issues, 5 NON-BLOCKING
Phase 2: Collate Findings and Present
→ Dispatch review-collation-agent
→ Collator compares both reviews
→ Present to user immediately:
Collated Report:
Common Issues (VERY HIGH):
- 2 BLOCKING issues both found
- 3 NON-BLOCKING issues both found
Exclusive Issues (MODERATE - cross-check starting):
- Agent #1 only: 1 BLOCKING, 4 NON-BLOCKING
- Agent #2 only: 2 BLOCKING, 2 NON-BLOCKING
Divergences: None
→ User notified: "Can `/revise common` now. Cross-check running..."
Phase 3: Cross-check Exclusive Issues (background)
→ Dispatch plan-review-agent to validate exclusive issues
→ For each exclusive issue, verify against requirements
→ Results:
- VALIDATED: 2 issues confirmed
- INVALIDATED: 3 issues don't apply
- UNCERTAIN: 1 issue needs user decision
→ User notified: "Cross-check complete. `/revise exclusive` or `/revise all`"
Example Usage: Documentation Review
User: Audit README.md and CLAUDE.md for accuracy
You: I'm using the dual-verification skill for comprehensive documentation audit.
Phase 1: Dual Independent Review
→ Dispatch 2 technical-writer agents in parallel
→ Each verifies docs against codebase
→ Agent #1 finds: 13 issues (1 critical, 3 high, 6 medium, 3 low)
→ Agent #2 finds: 13 issues (4 critical, 1 high, 4 medium, 4 low)
Phase 2: Collate Findings and Present
→ Dispatch review-collation-agent
→ Identifies: 7 common, 6 exclusive, 0 divergences
→ Present to user immediately:
Collated Report:
Common Issues (VERY HIGH): 7
- Missing mise commands (CRITICAL)
- Incorrect skill path (MEDIUM)
- Missing /verify command (HIGH)
Exclusive Issues (MODERATE - cross-check starting): 6
- Agent #1 only: 3 issues
- Agent #2 only: 3 issues
→ User notified: "Can `/revise common` now. Cross-check running..."
Phase 3: Cross-check Exclusive Issues (background)
→ Dispatch code-agent to verify exclusive claims against codebase
→ Results:
- VALIDATED: 4 issues (paths really don't exist, examples really broken)
- INVALIDATED: 2 issues (files exist, agent #1 missed them)
- UNCERTAIN: 0 issues
→ User notified: "Cross-check complete. `/revise exclusive` or `/revise all`"
Example Usage: Codebase Research
User: How does the authentication system work in this codebase?
You: I'm using the dual-verification skill for comprehensive research.
Phase 1: Dual Independent Research
→ Dispatch 2 Explore agents in parallel
→ Each investigates auth system independently
→ Agent #1 finds: JWT middleware, session handling, role-based access
→ Agent #2 finds: OAuth integration, token refresh, permission checks
Phase 2: Collate Findings and Present
→ Dispatch review-collation-agent
→ Identifies: 4 common findings, 3 unique insights, 1 divergence
→ Resolves divergence during collation
→ Present to user immediately:
Collated Report:
Common Findings (VERY HIGH): 4
- JWT tokens used for API auth (both found)
- Middleware in src/auth/middleware.ts (both found)
- Role enum defines permissions (both found)
- Refresh tokens stored in Redis (both found)
Exclusive Findings (MODERATE - cross-check starting): 3
- Agent #1: Found legacy session fallback for admin routes
- Agent #2: Found OAuth config for SSO integration
- Agent #2: Found rate limiting on auth endpoints
Divergence (RESOLVED):
- Token expiry: Agent #1 says 1 hour, Agent #2 says 24 hours
- → Verification: Config has 1h access + 24h refresh (both partially correct)
→ User notified: "Common findings ready. Cross-check running..."
Phase 3: Cross-check Exclusive Findings (background)
→ Dispatch Explore agent to verify exclusive claims
→ Results:
- VALIDATED: All 3 findings confirmed in codebase
- INVALIDATED: 0
- UNCERTAIN: 0
→ User notified: "Cross-check complete. All exclusive findings validated."
Related Skills
When to use this skill:
- Comprehensive reviews before major actions
- High-stakes decisions (execution, deployment, merge)
- Quality assurance for critical content
Related commands:
/cipherpowers:verify- Dispatches this skill for all verification types/cipherpowers:revise- Implements findings from verification (common, exclusive, all scopes)
Other review skills:
- verifying-plans: Single plan-review-agent (faster, less thorough)
- conducting-code-review: Single code-review-agent (regular reviews)
- maintaining-docs-after-changes: Single technical-writer (incremental updates)
Use dual-verification when stakes are high, use single-agent skills for regular work.
Common Mistakes
Mistake: "The reviews mostly agree, I'll skip detailed collation"
- Why wrong: Exclusive issues and subtle divergences matter
- Fix: Always use collation agent for systematic comparison
Mistake: "This exclusive issue is probably wrong since other reviewer didn't find it"
- Why wrong: May be valid edge case one reviewer caught
- Fix: Present with MODERATE confidence for user judgment, don't dismiss
Mistake: "I'll combine both reviews myself instead of using collation agent"
- Why wrong: Context overload, missing patterns, inconsistent categorization
- Fix: Always dispatch collation agent to handle comparison work
Mistake: "Two agents is overkill, I'll just run one detailed review"
- Why wrong: Missing the independence that catches different perspectives
- Fix: Use dual verification for high-stakes, single review for regular work
Mistake: "The divergence is minor, I'll pick one perspective"
- Why wrong: User needs to see both perspectives and make informed decision
- Fix: Mark as INVESTIGATE and let user decide
Remember
- Dispatch 2 agents in parallel for Phase 1 (efficiency)
- Use identical prompts for both agents (fairness)
- Dispatch collation agent for Phase 2 (context management)
- Present collation to user immediately after Phase 2 (user can
/revise common) - Dispatch cross-check agent for Phase 3 in background (parallel workflow)
- Common issues = VERY HIGH confidence (both found) → implement immediately
- Exclusive issues = MODERATE confidence → cross-check validates → VALIDATED/INVALIDATED/UNCERTAIN
- Divergences = resolved during collation (verification agent determines correct perspective)
- Cross-check enables parallel workflow: user starts
/revise commonwhile cross-check runs - Cost-benefit: Use for high-stakes, skip for trivial changes
Executing Plans
Overview
Load plan, review critically, execute tasks in batches, report for review between batches.
Core principle: Batch execution with checkpoints for architect review.
Announce at start: "I'm using the executing-plans skill to implement this plan."
The Process
Step 1: Load and Review Plan
- Read plan file
- Review critically - identify any questions or concerns about the plan
- If concerns: Raise them with your human partner before starting
- If no concerns: Create TodoWrite and proceed
Step 2: Execute Batch
Default: First 3 tasks
For each task:
-
Mark as in_progress
-
Select appropriate agent using semantic understanding (NOT keyword matching):
Analyze task requirements:
- What is the task type? (implementation, debugging, review, docs)
- What is the complexity? (simple fix vs multi-component investigation)
- What technology? (Rust vs other languages)
Agent selection:
- Rust implementation →
cipherpowers:rust-exec-agent(minimal context for literal execution) - General implementation →
cipherpowers:code-exec-agent(minimal context for literal execution) - Complex, multi-layered debugging →
cipherpowers:ultrathink-debugger - Documentation updates →
cipherpowers:technical-writer
IMPORTANT: Analyze the task semantically. Don't just match keywords.
- ❌ "don't use ultrathink" → ultrathink-debugger (keyword match)
- ✅ "don't use ultrathink" → general-purpose (semantic understanding)
See selecting-agents skill for detailed selection criteria.
-
Dispatch agent with embedded following-plans skill:
Include in agent prompt:
IMPORTANT: You MUST follow the plan exactly as specified. Read and follow: @${CLAUDE_PLUGIN_ROOT}skills/following-plans/SKILL.md This skill defines when you can make changes vs when you must report BLOCKED. REQUIRED: Your completion report MUST include STATUS: - STATUS: OK (task completed as planned) - STATUS: BLOCKED (plan approach won't work, need approval for deviation) The plan approach was chosen for specific reasons during design. Do NOT rationalize "simpler" approaches without approval. -
Follow each step exactly (plan has bite-sized steps)
-
Run verifications as specified
-
Check agent completion status:
- STATUS: OK → Mark as completed, continue
- STATUS: BLOCKED → STOP, handle escalation (see Handling BLOCKED Status)
- No STATUS → Agent violated protocol, escalate
Step 3: Review Batch (REQUIRED)
**REQUIRED SUB-SKILL:** Use cipherpowers:requesting-code-reviewAfter batch complete:
- Follow requesting-code-review skill to dispatch code-review-agent
- Fix BLOCKING issues before continuing to next batch
- Address NON-BLOCKING feedback or defer with justification
Code review is mandatory between batches. No exceptions.
Optional: If concerned about plan adherence, user can request /verify execute for dual-verification of batch implementation vs plan specification.
Step 4: Report
When batch complete:
- Show what was implemented
- Show verification output
- Say: "Ready for feedback."
Step 5: Continue
Based on feedback:
- Apply changes if needed
- Execute next batch
- Repeat until complete
Step 6: Complete Development
After all tasks complete and verified:
- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
- REQUIRED SUB-SKILL: Use cipherpowers:finishing-a-development-branch
- Follow that skill to verify tests, present options, execute choice
When to Stop and Ask for Help
STOP executing immediately when:
- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
- Plan has critical gaps preventing starting
- You don't understand an instruction
- Verification fails repeatedly
Ask for clarification rather than guessing.
When to Revisit Earlier Steps
Return to Review (Step 1) when:
- Partner updates the plan based on your feedback
- Fundamental approach needs rethinking
Don't force through blockers - stop and ask.
Handling BLOCKED Status
When an agent reports STATUS: BLOCKED:-
Read the BLOCKED reason carefully
- What does agent say won't work?
- What deviation does agent want to make?
-
Review plan and design context
- Why was this approach chosen?
- Was the agent's "simpler" approach already considered and rejected?
-
Ask user what to do via AskUserQuestion:
Agent reported BLOCKED on: {task} Reason: {agent's reason} Plan specified: {planned approach} Agent wants: {agent's proposed deviation} Options: 1. Trust agent - approve deviation from plan 2. Revise plan - update task with different approach 3. Enforce plan - agent must follow plan as written 4. Investigate - need more context before deciding -
Execute user decision:
- Approve → Update plan, re-dispatch agent with approved approach
- Revise → Update plan file, re-dispatch agent
- Enforce → Re-dispatch agent with stronger "follow plan" guidance
- Investigate → Pause execution, gather more information
Never approve deviations without user input.
Related Skills
Agent selection guidance:
- Selecting Agents:
${CLAUDE_PLUGIN_ROOT}skills/selecting-agents/SKILL.md
Code review workflow:
- Requesting Code Review:
${CLAUDE_PLUGIN_ROOT}skills/requesting-code-review/SKILL.md
Finishing work:
- Finishing a Development Branch:
${CLAUDE_PLUGIN_ROOT}skills/finishing-a-development-branch/SKILL.md
Plan compliance:
- Following Plans:
${CLAUDE_PLUGIN_ROOT}skills/following-plans/SKILL.md
Remember
- Review plan critically first
- Embed following-plans skill in agent prompts
- Select the right agent using semantic understanding (not keyword matching)
- Check for STATUS in agent completions
- Handle BLOCKED status by asking user (never auto-approve deviations)
- Code review after every batch (mandatory)
- User can request
/verify executeif concerned about plan adherence - Don't skip verifications
- Reference skills when plan says to
- Between batches: just report and wait
- Stop when blocked, don't guess
Finishing a Development Branch
Overview
Guide completion of development work by presenting clear options and handling chosen workflow.
Core principle: Verify tests → Present options → Execute choice → Clean up.
Announce at start: "I'm using the finishing-a-development-branch skill to complete this work."
The Process
Step 1: Verify Tests
Before presenting options, verify tests pass:
Run project test command
If tests fail:
Tests failing (<N> failures). Must fix before completing:
[Show failures]
Cannot proceed with merge/PR until tests pass.
Stop. Don't proceed to Step 2.
If tests pass: Continue to Step 2.
Step 2: Determine Base Branch
# Try common base branches
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
Or ask: "This branch split from main - is that correct?"
Step 3: Present Options
Present exactly these 4 options:
Implementation complete. What would you like to do?
1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work
Which option?
Don't add explanation - keep options concise.
Step 4: Execute Choice
Option 1: Merge Locally
# Switch to base branch
git checkout <base-branch>
# Pull latest
git pull
# Merge feature branch
git merge <feature-branch>
# Verify tests on merged result
<test command>
# If tests pass
git branch -d <feature-branch>
Then: Cleanup worktree (Step 5)
Option 2: Push and Create PR
# Push branch
git push -u origin <feature-branch>
# Create PR
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed>
## Test Plan
- [ ] <verification steps>
EOF
)"
Then: Cleanup worktree (Step 5)
Option 3: Keep As-Is
Report: "Keeping branch . Worktree preserved at ."
Don't cleanup worktree.
Option 4: Discard
Confirm first:
This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>
Type 'discard' to confirm.
Wait for exact confirmation.
If confirmed:
git checkout <base-branch>
git branch -D <feature-branch>
Then: Cleanup worktree (Step 5)
Step 5: Cleanup Worktree
For Options 1, 2, 4:
Check if in worktree:
git worktree list | grep $(git branch --show-current)
If yes:
git worktree remove <worktree-path>
For Option 3: Keep worktree.
Quick Reference
| Option | Merge | Push | Keep Worktree | Cleanup Branch |
|---|---|---|---|---|
| 1. Merge locally | ✓ | - | - | ✓ |
| 2. Create PR | - | ✓ | ✓ | - |
| 3. Keep as-is | - | - | ✓ | - |
| 4. Discard | - | - | - | ✓ (force) |
Common Mistakes
Skipping test verification
- Problem: Merge broken code, create failing PR
- Fix: Always verify tests before offering options
Open-ended questions
- Problem: "What should I do next?" → ambiguous
- Fix: Present exactly 4 structured options
Automatic worktree cleanup
- Problem: Remove worktree when might need it (Option 2, 3)
- Fix: Only cleanup for Options 1 and 4
No confirmation for discard
- Problem: Accidentally delete work
- Fix: Require typed "discard" confirmation
Red Flags
Never:
- Proceed with failing tests
- Merge without verifying tests on result
- Delete work without confirmation
- Force-push without explicit request
Always:
- Verify tests before offering options
- Present exactly 4 options
- Get typed confirmation for Option 4
- Clean up worktree for Options 1 & 4 only
Integration
Called by:
- subagent-driven-development (Step 7) - After all tasks complete
- executing-plans (Step 5) - After all batches complete
Pairs with:
- using-git-worktrees - Cleans up worktree created by that skill
Following Plans
Overview
This skill is embedded in agent prompts during plan execution. It provides an algorithmic decision tree for determining when to follow the plan exactly vs when to report BLOCKED.
Purpose: Prevent agents from rationalizing "simpler approaches" that were already considered and rejected during design.
When to Use
This skill is embedded in agent prompts during plan execution. It applies when:
- Agent executing implementation plan encounters situation requiring deviation
- Current approach in plan seems problematic or won't work
- Agent discovers syntax errors or naming issues in plan
- Agent wants to use "simpler approach" than plan specifies
- Tests fail with planned approach
- Plan contains contradictions or errors
This skill prevents:
- Unauthorized architectural changes during execution
- Scope creep from "better ideas" during implementation
- Rationalization of deviations without approval
- Silent changes that break plan assumptions
Quick Reference
Is change syntax/naming only?
├─ YES → Fix it, note in completion, STATUS: OK
└─ NO → Does it change approach/architecture?
├─ YES → Report STATUS: BLOCKED with reason
└─ NO → Follow plan exactly, STATUS: OK
Allowed without BLOCKED:
- Syntax corrections (wrong function name in plan)
- Error handling implementation details
- Variable naming choices
- Code organization within file
- Test implementation details
Requires BLOCKED:
- Different algorithm or approach
- Different library/framework
- Different data structure/API design
- Skipping/adding planned functionality
- Refactoring not in plan
Algorithmic Decision Tree
Follow this exactly. No interpretation.
Step 1: Check if this is a syntax/naming fix
Is the change you want to make limited to:
- Correcting function/variable names
- Fixing syntax errors
- Updating import paths
- Correcting typos in code
YES → Make the change
Add note to task completion: "Fixed syntax: {what you fixed}"
Continue to Step 4
NO → Continue to Step 2
Step 2: Check if this changes approach/architecture
Does your change alter:
- The overall approach or algorithm
- The architecture or structure
- Which libraries/frameworks to use
- The data model or API design
YES → STOP
Report STATUS: BLOCKED
Continue to Step 3
NO → Continue to Step 4
Step 3: Report BLOCKED (Required Format)
``` STATUS: BLOCKED REASON: [Explain why plan approach won't work and what you want to do instead] TASK: [Task identifier from plan]Example: STATUS: BLOCKED REASON: Plan specifies JWT auth but existing service uses OAuth2. Implementing JWT would require refactoring auth service. TASK: Task 3 - Implement authentication middleware
**STOP HERE. Do not proceed with implementation.**
</EXTREMELY-IMPORTANT>
### Step 4: Follow plan exactly
Implement the task exactly as specified in plan.
Report STATUS: OK when complete.
## Status Reporting (REQUIRED)
<EXTREMELY-IMPORTANT>
**Every task completion MUST include STATUS.**
</EXTREMELY-IMPORTANT>
### STATUS: OK
Use when task completed as planned:
STATUS: OK TASK: Task 3 - Implement authentication middleware SUMMARY: Implemented JWT authentication middleware per plan specification.
### STATUS: BLOCKED
Use when plan approach won't work:
STATUS: BLOCKED REASON: [Clear explanation] TASK: [Task identifier]
**Missing STATUS = gate will block you from proceeding.**
## Red Flags (Rationalization Defense)
If you're thinking ANY of these thoughts, you're about to violate the plan:
| Thought | Reality |
|---------|---------|
| "This simpler approach would work better" | Simpler approach was likely considered and rejected in design. Report BLOCKED. |
| "The plan way seems harder than necessary" | Plan reflects design decisions you don't have context for. Follow plan or report BLOCKED. |
| "I can just use library X instead" | Library choice is architectural decision. Report BLOCKED. |
| "This is a minor architectural change" | All architecture changes require approval. Report BLOCKED. |
| "The tests would pass if I just..." | Making tests pass ≠ meeting requirements. Follow plan or report BLOCKED. |
| "I'll note the deviation in my summary" | Deviations require explicit approval BEFORE implementation. Report BLOCKED. |
**All of these mean: STOP. Report STATUS: BLOCKED.**
## What Counts as "Following Plan Exactly"
**Allowed without BLOCKED:**
- Syntax corrections (wrong function name in plan)
- Error handling implementation details (plan says "validate input", you choose validation approach)
- Variable naming (plan says "store user data", you choose variable name)
- Code organization within a file (where to place helper functions)
- Test implementation details (plan says "add tests", you write specific test cases)
**Requires BLOCKED:**
- Different algorithm or approach
- Different library/framework
- Different data structure
- Different API design
- Skipping planned functionality
- Adding unplanned functionality
- Refactoring not in plan
## Common Scenarios
### Scenario: Plan has wrong function name
Plan says: "Call getUserData()" Reality: Function is actually getUser()
Decision: Fix syntax Action: Use getUser(), note in completion Status: OK
### Scenario: Plan approach seems unnecessarily complex
Plan says: "Implement manual JWT verification" Your thought: "Library X does this better and simpler"
Decision: Architectural change Action: Report BLOCKED Status: BLOCKED Reason: Plan specifies manual JWT verification but library X provides simpler approach. Should we use library instead?
### Scenario: Tests fail with planned approach
Plan says: "Use synchronous file reads" Reality: Tests timeout with sync reads, async would fix
Decision: Approach change Action: Report BLOCKED Status: BLOCKED Reason: Synchronous file reads cause test timeouts. Need async approach or different solution.
### Scenario: Plan contradicts itself
Plan Task 3: "Use PostgreSQL" Plan Task 5: "Query MongoDB"
Decision: Plan error Action: Report BLOCKED Status: BLOCKED Reason: Plan specifies both PostgreSQL (Task 3) and MongoDB (Task 5). Which should be used?
## Common Mistakes
**Mistake:** "This simpler approach would work better"
- **Why wrong:** Simpler approach was likely considered and rejected in design
- **Fix:** Report STATUS: BLOCKED, don't implement
**Mistake:** "This is a minor architectural change"
- **Why wrong:** All architecture changes require approval
- **Fix:** Report STATUS: BLOCKED for any approach/architecture change
**Mistake:** "I'll note the deviation in my summary"
- **Why wrong:** Deviations require explicit approval BEFORE implementation
- **Fix:** Report STATUS: BLOCKED before making changes
**Mistake:** "The tests would pass if I just use library X instead"
- **Why wrong:** Making tests pass ≠ meeting requirements, library choice is architectural
- **Fix:** Report STATUS: BLOCKED, explain issue
**Mistake:** "Forgot to include STATUS in my completion report"
- **Why wrong:** Missing STATUS = gate will block you from proceeding
- **Fix:** Always include STATUS: OK or STATUS: BLOCKED
## Remember
- **Syntax fixes**: Allowed (note in completion)
- **Approach changes**: Report BLOCKED
- **Architecture changes**: Report BLOCKED
- **Plan errors**: Report BLOCKED
- **Always provide STATUS**: OK or BLOCKED
- **When in doubt**: Report BLOCKED
**Better to report BLOCKED unnecessarily than to deviate from plan without approval.**
Maintaining Documentation After Code Changes
Overview
Documentation drift is inevitable without systematic maintenance. Code evolves rapidly while documentation becomes stale. This skill provides a two-phase workflow to keep project docs synchronized with code: analyze recent changes, then update and restructure documentation accordingly.
When to Use
Use this skill when:
- Completing features or bugfixes (before marking work complete)
- Preparing to merge branches or create pull requests
- Git diff shows significant code changes
- Documentation feels stale, incomplete, or contradicts current code
- New functionality added without corresponding doc updates
- Onboarding reveals outdated or missing documentation
- API changes or new commands/tasks added
- Implementation challenges revealed better practices
When NOT to use:
- During active development (docs can lag slightly, update at checkpoints)
- For trivial changes (typo fixes, formatting)
- When no code has changed
Critical Principle
Maintaining existing documentation after code changes is NOT "proactively creating docs" - it's keeping current docs accurate.
CLAUDE.md instructions about "don't proactively create documentation" apply to NEW documentation files for undocumented features. They do NOT apply to maintaining existing documentation after you change the code it documents.
If you changed the code, you must update the corresponding documentation. No exceptions.
Common Rationalizations (And Why They're Wrong)
| Rationalization | Reality |
|---|---|
| "I'll update docs in a follow-up PR" | Later rarely happens. Context is freshest now. Capture it. |
| "Commit messages are documentation enough" | Commit messages explain code changes, not user workflows. Both are needed. |
| "Code is self-documenting if well-written" | Code shows HOW. Docs explain WHY and usage patterns. Different purposes. |
| "Time pressure means ship now, document later" | Shipping undocumented changes creates support burden > time saved. |
| "Don't know if user wants docs updated" | If code changed, docs MUST update. Not optional. Ask about scope, not whether. |
| "Documentation is maintenance overhead" | Outdated docs are overhead. Current docs save time for everyone. |
| "Minimal accurate > comprehensive outdated" | False choice. This skill gives you accurate AND complete in 15-30 min. |
| "Different teams handle docs differently" | This skill IS the standard for this project. Follow it. |
| "Risk of making commit scope too large" | Documentation changes belong with code changes. Same PR = atomic change. |
| "Best practices docs only change for patterns" | If you discovered lessons during implementation, they belong in CLAUDE.md. |
None of these are valid reasons to skip documentation maintenance.
Quick Reference
| Phase | Focus | Key Activities |
|---|---|---|
| Analyze | What changed? | git diff → review docs → identify gaps |
| Update | Sync docs | Update content → restructure → summarize changes |
Implementation
Phase 1: Analysis
Goal: Understand what changed and what documentation needs updating
-
Review recent changes:
git diff [base-branch]...HEADExamine the full diff to understand scope of changes
-
Check existing documentation:
- README.md (main project docs)
- CLAUDE.md (AI assistant guidance) - use
cipherpowers:maintaining-instruction-filesfor size/quality - AGENTS.md (multi-agent instructions) - use
cipherpowers:maintaining-instruction-filesfor size/quality - README_*.md (specialized documentation)
- docs/ directory (practices, examples, plans)
- Any project-specific doc locations
-
Identify documentation gaps:
- New features without usage examples
- Changed APIs without updated references
- Implementation lessons not captured in CLAUDE.md
- New best practices discovered during work
- Implementation challenges and solutions
- Known issues or limitations discovered
- Commands/tasks that changed behavior
Output of analysis phase: List of specific documentation updates needed
Phase 2: Update
Goal: Bring documentation into sync with current code
-
Update content to reflect changes:
- Add new sections for new features
- Update changed functionality (especially examples)
- Document implementation details for complex components
- Update usage examples with new functionality
- Add troubleshooting tips from recent issues
- Update best practices based on experience
- Verify commands/tasks reflect current behavior
-
Restructure for clarity:
- Remove outdated or redundant content
- Group related topics together
- Split large files if they've grown unwieldy
- Fix broken cross-references
- Ensure consistent formatting
-
Document updates: Provide summary of changes:
- Files updated
- Major documentation changes
- New best practices added
- Sections removed or restructured
Documentation Standards
Follow project documentation standards defined in:
- ${CLAUDE_PLUGIN_ROOT}standards/documentation.md
Key standards to verify:
- Formatting and structure (headings, examples, status indicators)
- Content completeness (usage examples, troubleshooting)
- README organization (concise main file, README_*.md for specialized docs)
Common Mistakes
| Mistake | Fix |
|---|---|
| Updating only README, missing other docs | Check CLAUDE.md, README_*.md, docs/ systematically |
| Not reviewing git diff | Always start with full diff to understand scope |
| Describing "what" without "why" | Explain rationale, not just functionality |
| Forgetting to update examples | Changed APIs must update all examples |
| Batch updating at project end | Update at natural checkpoints (feature complete, before merge) |
| Restructuring separately from updates | Restructure while updating to prevent redundant passes |
| Missing troubleshooting updates | Document edge cases and solutions discovered during work |
What NOT to Skip
These are consistently skipped under pressure. Check explicitly:
✅ MUST check every time:
- git diff reviewed (full diff, not just summary)
- CLAUDE.md updated (best practices, lessons learned, implementation patterns)
- All README*.md files checked and updated
- Practices docs (principles/standards/workflows) updated if patterns changed
- docs/examples/ updated if usage changed
- Usage examples updated (not just prose)
- Troubleshooting section updated (if you debugged issues)
- Cross-references verified (links still work)
Common blind spots:
- CLAUDE.md (agents forget this captures lessons learned)
- Usage examples (agents update text but not code examples)
- Troubleshooting sections (agents assume commit messages are enough)
- Practices documentation (agents think only patterns change these)
Red Flags - STOP and Review Docs
Situations:
- About to merge without checking documentation
- Examples still show old API or command syntax
- CLAUDE.md doesn't mention new patterns/practices discovered
- Onboarding someone would miss new functionality
- Can't remember what changed (didn't check git diff)
- Just finished debugging but no troubleshooting docs added
Rationalizations (means you're about to skip docs):
- "I'll update docs later"
- "Commit message is enough"
- "Code is self-documenting"
- "Time pressure"
- "User said ship it"
- "Not sure what user wants"
- "Different teams do it differently"
- "Don't want to overstep"
All of these mean: Stop and run this workflow before proceeding.
Real-World Impact
Without systematic maintenance:
- Onboarding takes longer (outdated docs)
- Best practices lost (not captured in CLAUDE.md)
- Teammates confused by stale examples
- Support burden increases (troubleshooting not documented)
- Knowledge silos (changes not shared)
With this workflow:
- Documentation stays current
- Best practices captured immediately
- Onboarding smooth and accurate
- Troubleshooting knowledge preserved
- Team aligned on current patterns
Integration with Commands/Agents
This skill can be invoked by:
- Commands that dispatch to doc-writer subagent
- Manual workflow when preparing to merge
- Pre-merge checklist item
- Code review requirement
Commands should provide context about documentation practices and reference this skill for methodology.
Maintaining Instruction Files
Overview
Specialized workflow for AI instruction files (CLAUDE.md, AGENTS.md). Different from general documentation:
- Size-constrained: <200 lines ideal, <300 max
- AI-audience: Directive style, third-person
- Progressive disclosure: Reference docs/, don't include content
- Multi-agent: AGENTS.md standard works with any AI assistant
Why this matters: Quality instruction files create a virtuous cycle - better context leads to better AI output, which builds trust, which leads to more investment in refined guidance. Poorly maintained instruction files cause the opposite: AI makes mistakes, trust erodes, teams abandon the approach.
Announce at start: "I'm using the maintaining-instruction-files skill to work on this instruction file."
Critical Infrastructure Warning: Instruction files are NOT documentation - they're critical infrastructure that shapes every AI interaction. A single poorly-thought-out line can mislead the AI in every session. Never accept auto-generated instruction files without careful manual review and curation.
Terminology note: These files are sometimes called "memory files" in multi-agent literature (as in agents-md-best-practices.md), but we use "instruction files" to emphasize their directive role in shaping AI behavior rather than storing information.
When to Use
Use this skill when:
- Creating new CLAUDE.md or AGENTS.md
- Instruction file exceeds 200 lines (warning) or 300 lines (action required)
- Adding content to instruction files
- Migrating CLAUDE.md to AGENTS.md standard
- Auditing instruction file quality
- Reviewing PRs that modify instruction files
When NOT to use:
- General documentation updates (use maintaining-docs-after-changes)
- Creating docs/ content (use organizing-documentation)
- Trivial typo fixes
Quick Reference
| Size | Status | Action |
|---|---|---|
| <200 lines | ✅ Good | Maintain quality |
| 200-300 lines | ⚠️ Warning | Consider extraction |
| >300 lines | ❌ Action required | Run extraction workflow |
| Principle | Implementation |
|---|---|
| Size discipline | Count lines, extract if >300 |
| Universal relevance | Remove edge cases |
| Tool-first | Reference skills/linters, not rules |
| Reference, don't include | Link to docs/, don't duplicate |
| Multi-agent neutral | No "Claude should...", use AGENTS.md |
Core Principles
0. Context Window is Precious
The AI's context window is limited and valuable - fill it with high-value information, not exhaustive minutiae. Every token spent on instruction files is a token not available for actual work context.
Research finding: As instruction count increases, model performance in following them degrades linearly. Even frontier models show this effect. Smaller models are especially prone to instruction overload.
Claude Code behavior: Claude's system actively tells the model to skip context files unless they're highly relevant to the current task. If most content appears irrelevant, the model may ignore the entire file. This means bloated instruction files can be worse than no instruction file at all.
1. Size Discipline
# Check current size
wc -l AGENTS.md CLAUDE.md 2>/dev/null || wc -l CLAUDE.md
Thresholds:
- <200 lines: Ideal, focused and effective
- 200-300 lines: Warning, review for extraction opportunities
-
300 lines: Must extract content to docs/
Optimization target: Minimize instruction count, not just line count. Fewer well-chosen instructions outperform many rules. Aim for the minimum guidance that covers essential context.
What counts as "one instruction"?
Multiple instructions (counted separately by AI):
- Always run tests before committing
- Always run linting before committing
- Always run type checking before committing
Single instruction (counted as one):
- Run all quality checks before committing: `npm run test && npm run lint && npm run typecheck`
Consolidation strategies:
- Combine related checks into one command
- Group by workflow stage instead of tool
- Use scripts that run multiple checks
- Reference skills instead of listing steps
2. Universal Relevance
Every line must apply to most tasks. Test each section:
- "Does this apply when fixing bugs?" → Must be Yes
- "Does this apply when adding features?" → Must be Yes
- "Is this only relevant for [specific scenario]?" → If Yes, extract to docs/
3. Tool-First Content
Wrong: Listing style rules in instruction file
## Code Style
- Use camelCase for variables
- 2-space indentation
- No trailing whitespace
Right: Reference tools
## Code Style
Use project linters and formatters. Run `npm run lint` before commits.
4. Reference, Don't Include (Progressive Disclosure)
This principle implements progressive disclosure - a pattern where detailed information is available but not loaded until needed.
Why it works:
- AI assistants can follow links to fetch detailed docs when relevant
- Main instruction file stays light, focused on universal context
- Detailed instructions are available but not consuming context window space in every session
- AI decides what to fetch based on current task
Pattern:
- Keep 2-3 sentence summary in instruction file
- Link to detailed doc with "See [path] for details"
- AI fetches detailed doc only when working on related tasks
Wrong: Duplicating content
## Architecture
[50 lines of architecture details]
Right: Linking to docs
## Architecture
High-level: [2-3 sentences]
See `docs/UNDERSTAND/architecture.md` for detailed architecture.
5. On-Demand Knowledge via Platform Tools
Extend the tool-first principle beyond linters to full platform capabilities:
Available platform tools:
- Skills: Reusable workflows invoked when needed (
Skill(skill: "name")) - Hooks: Automated actions triggered by events (pre-commit, session-start)
- MCP servers: External tools and data sources
- Slash commands: User-triggered context injection
Pattern: Instead of front-loading all possible context, configure tools to provide context on-demand:
Wrong: Putting everything in instruction file
## API Guidelines
[100 lines of API patterns, error handling, authentication...]
Right: Reference skill that provides guidance when needed
## API Guidelines
Use project API patterns. Skill `cipherpowers:api-patterns` provides detailed guidance.
Benefits:
- Instruction file stays concise
- Detailed guidance available when actually needed
- Context window used efficiently
- Guidance can be updated in one place (the skill/tool)
More examples:
Wrong: Putting git workflow in instruction file
## Git Workflow
1. Create feature branch from main
2. Make atomic commits with conventional format
3. Run tests before committing
4. Create PR with template
5. Request review from team lead
6. Address feedback and re-request
7. Squash merge after approval
Right: Reference commit skill
## Git Workflow
Use `/cipherpowers:commit` for atomic commits. Skill: `cipherpowers:commit-workflow`
Wrong: Listing all debugging techniques
## Debugging
- Use debugger breakpoints for step-through
- Add logging statements at key points
- Check error messages and stack traces
- Review recent changes in git log
- Test with minimal reproduction case
[... 20 more techniques]
Right: Reference debugging skill
## Debugging
Use `cipherpowers:systematic-debugging` for investigation workflow.
6. Multi-Agent Neutral
Wrong: Claude-specific
Claude should always check tests before...
Right: Agent-neutral
Always check tests before...
Validation Checklist
Run before completing any instruction file work:
- Line count <300 (warn >200):
wc -l [file] - No edge-case instructions (extract to docs/)
- Commands actually work (execute to verify)
- References use correct paths (
${CLAUDE_PLUGIN_ROOT}or relative) - No duplicated content from standards/ or docs/
- Links to docs/BUILD/00-START/ for prerequisites
- Links to docs/LOOKUP/ for quick references
- Agent-neutral wording (no "Claude should...")
Extraction Workflow
When instruction file exceeds 300 lines:
Step 1: Categorize Content
Review each section and categorize:
| Category | Target Location | Criteria |
|---|---|---|
| Prerequisites | docs/BUILD/00-START/ | Required before any work |
| Deep dives | docs/UNDERSTAND/ | Detailed explanations |
| Quick refs | docs/LOOKUP/ | < 30 second lookups |
| Edge cases | docs/BUILD/02-IMPLEMENT/ | Specific scenarios |
Step 2: Extract Content
Move content to appropriate docs/ location:
# Before (in AGENTS.md - 50 lines)
## Database Schema
[Detailed schema documentation...]
# After (in AGENTS.md - 3 lines)
## Database
See `docs/UNDERSTAND/database-schema.md` for schema documentation.
Step 3: Verify References
- All extracted content accessible via links
- No broken references
- Index files updated if applicable
Step 4: Recount
wc -l AGENTS.md
Should now be <300 (ideally <200).
Multi-Agent Compatibility
AGENTS.md Standard
AGENTS.md is the open standard recognized by:
- Claude Code (Anthropic)
- GitHub Copilot
- Cursor
- Sourcegraph Cody
- Other AI assistants
Relationship Patterns
Pattern A: Universal file only
AGENTS.md ← All instructions here
CLAUDE.md (symlink → AGENTS.md)
Pattern B: Universal + extensions
AGENTS.md ← Universal instructions
CLAUDE.md ← Includes @AGENTS.md + Claude-specific
Pattern C: Claude-only (legacy)
CLAUDE.md ← All instructions
Recommend migrating to Pattern A or B.
Migration from CLAUDE.md to AGENTS.md
- Audit CLAUDE.md for Claude-specific content
- Extract universal content to new AGENTS.md
- Either:
- Create symlink:
ln -s AGENTS.md CLAUDE.md - Or keep CLAUDE.md with
@AGENTS.mdinclude
- Create symlink:
Creating a Symlink
On Unix/Linux/macOS:
# Create symbolic link (use this for git repos)
ln -s AGENTS.md CLAUDE.md
# Verify it works
ls -l CLAUDE.md # Should show: CLAUDE.md -> AGENTS.md
cat CLAUDE.md # Should show AGENTS.md content
Important:
- Use symbolic links (soft links), not hard links
- Commit the symlink to git (works cross-platform)
- Test that both files are recognized by Claude Code
Verification checklist:
-
ls -l CLAUDE.mdshows symlink arrow (->) -
cat CLAUDE.mddisplays AGENTS.md content - Both files recognized by Claude Code
- Symlink committed to git
Platform-Specific Tuning
Different AI systems have different quirks. A Claude-optimized instruction file may not work as effectively with GitHub Copilot directly, and vice versa.
Keep core content the same across platforms, but be prepared to tweak:
- Context window handling differs
- Prompt format preferences vary
- Tool/skill integration differs
When to adapt:
- If AI consistently misinterprets instructions on one platform
- If certain sections seem ignored on specific platforms
- If switching between platforms produces notably different results
Adaptation strategy:
- Keep shared AGENTS.md as single source of truth
- Use platform-specific extensions (CLAUDE.md) for platform-specific tweaks
- Test instructions on each platform you support
Iterative Refinement
Instruction files are living documents. Update them as your project evolves and as you learn what helps the AI most.
Review triggers:
- After onboarding new team members (they reveal unclear instructions)
- After major feature changes (architecture may need updating)
- When AI makes repeated mistakes (instructions may be unclear or missing)
- Quarterly review (prevent drift and bloat)
Refinement process:
- Identify patterns in AI mistakes or confusion
- Test instruction changes with real tasks
- Remove instructions that aren't consistently helping
- Add instructions only when there's a demonstrated need
Avoid: Adding instructions preemptively "just in case" - this leads to bloat. Add based on observed need.
Common Rationalizations
| Excuse | Reality |
|---|---|
| "This rule is important" | If not universal, it goes in docs/ |
| "It's only 350 lines" | Models ignore bloated files - attention drops linearly |
| "I'll trim it later" | Size grows, never shrinks without active management |
| "I need it all in one file" | Progressive disclosure via references works better |
| "Users expect comprehensive docs" | Users expect working AI - bloat prevents that |
| "These are all critical rules" | Test: applies to bug fixes AND features? If not, extract |
Common Mistakes
| Mistake | Fix |
|---|---|
| Adding rules instead of tool references | Point to linters, skills, hooks |
| Including full content from docs | Link with brief summary only |
| Using Claude-specific language | Rewrite agent-neutral |
| Ignoring line count | Check wc -l every edit |
| Creating parallel hierarchy | Reference existing docs/ structure |
| Not verifying commands | Execute each command to test |
Related Skills
${CLAUDE_PLUGIN_ROOT}skills/maintaining-docs-after-changes/SKILL.md- General doc sync${CLAUDE_PLUGIN_ROOT}skills/capturing-learning/SKILL.md- Adding lessons learned${CLAUDE_PLUGIN_ROOT}skills/organizing-documentation/SKILL.md- docs/ structure
References
- Template:
${CLAUDE_PLUGIN_ROOT}templates/agents-md-template.md - Documentation Structure:
${CLAUDE_PLUGIN_ROOT}standards/documentation-structure.md - Best Practices Research:
agents-md-best-practices.md
Organizing Documentation
Overview
Transform documentation from content-type organization (architecture/, testing/, api/) to intent-based organization (BUILD/, FIX/, UNDERSTAND/, LOOKUP/).
Announce at start: "I'm using the organizing-documentation skill to structure these docs by developer intent."
When to Use
- Setting up documentation for a new project
- Existing docs are hard to navigate
- New team members can't find what they need
- Same questions keep getting asked
- Docs exist but nobody reads them
The Process
Step 1: Audit Existing Documentation
List all docs and categorize by actual developer intent:
| File | Current Location | Developer Intent | New Location |
|------|-----------------|------------------|--------------|
| architecture.md | docs/ | Understand system | UNDERSTAND/core-systems/ |
| testing-guide.md | docs/ | Build tests | BUILD/03-TEST/ |
| error-codes.md | docs/ | Quick lookup | LOOKUP/ |
| debugging-tips.md | docs/ | Fix problems | FIX/investigation/ |
Key question: "When would a developer reach for this doc?"
Step 2: Create Directory Structure
mkdir -p docs/{BUILD/{00-START,01-DESIGN,02-IMPLEMENT,03-TEST,04-VERIFY},FIX/{symptoms,investigation,solutions},UNDERSTAND/{core-systems,evolution},LOOKUP}
Step 3: Populate 00-START First
Critical: This is the entry point. Include:
- Prime directive - Non-negotiable project rules
- Architecture overview - High-level system map
- Coordinate systems/conventions - Domain-specific foundations
Without 00-START, developers skip prerequisites.
Step 4: Organize FIX by Symptoms
Wrong: Organize by root cause (memory-leaks/, type-errors/) Right: Organize by what developer sees (visual-bugs/, test-failures/)
FIX/symptoms/
├── visual-bugs/
│ ├── rendering-wrong.md
│ └── layout-broken.md
├── test-failures/
│ └── passes-locally-fails-ci.md
└── performance/
└── slow-startup.md
Step 5: Create LOOKUP Quick References
Rule: < 30 seconds to find and use.
Good LOOKUP content:
- Keyboard shortcuts
- Command cheat sheets
- Error code tables
- ID registries
- One-page summaries
Bad LOOKUP content (move elsewhere):
- Tutorials (→ BUILD/02-IMPLEMENT)
- Explanations (→ UNDERSTAND)
- Debugging guides (→ FIX)
Step 6: Build INDEX.md
Create master index with purpose annotations:
## BUILD
| File | Title | Purpose |
|------|-------|---------|
| `00-START/prime-directive.md` | Prime Directive | Non-negotiable rules |
| `02-IMPLEMENT/patterns.md` | Code Patterns | How to implement features |
Purpose column is mandatory - it's the key to discoverability.
Step 7: Add Redirects
Don't break existing links. Create README.md in old locations:
# This content has moved
Documentation has been reorganized by developer intent.
- Architecture docs → `UNDERSTAND/core-systems/`
- Testing docs → `BUILD/03-TEST/`
- Quick references → `LOOKUP/`
See `docs/INDEX.md` for complete navigation.
Checklist
- All docs audited and categorized by intent
- BUILD/00-START has prerequisites
- FIX organized by symptoms, not causes
- LOOKUP items are < 30 second lookups
- INDEX.md has purpose column
- Old locations have redirects
- Internal links verified
Anti-Patterns
Don't:
- Create deep nesting (max 3 levels)
- Duplicate content across directories
- Put tutorials in LOOKUP
- Organize FIX by root cause
- Skip the INDEX.md
Do:
- Keep structure flat where possible
- Cross-reference between sections
- Update INDEX.md as docs change
- Test navigation with new team member
Additional Patterns
README-Per-Directory
Every directory needs README.md with consistent structure:
- Purpose statement
- "Use this when" section
- Navigation to contents
- Quick links to related sections
Use template: ${CLAUDE_PLUGIN_ROOT}templates/documentation-readme-template.md
Dual Navigation
Maintain parallel navigation:
- NAVIGATION.md - Task-based primary (80%)
- INDEX.md - Concept-based fallback (20%)
Naming Conventions
- ALLCAPS for document types: SUMMARY.md, QUICK-REFERENCE.md
- Numeric prefixes for sequence: 00-START/, 01-DESIGN/
- Lowercase-dashes for content: api-patterns.md
Progressive Disclosure
Provide multiple entry points by time budget:
- 5 min: TL;DR section
- 20 min: README + key sections
- 2 hours: Full documentation
Role-Based Paths
Create reading paths for different roles with:
- Goal statement
- Reading order
- Time estimate
- Key takeaway
Integration with Instruction Files
AGENTS.md and CLAUDE.md should reference the docs/ structure using progressive disclosure:
Pattern:
- Keep 2-3 sentence summary in instruction file
- Link to detailed doc: "See
docs/BUILD/00-START/for prerequisites" - AI fetches detailed docs only when needed
When reorganizing docs/:
- Update AGENTS.md/CLAUDE.md references to match new paths
- Use
cipherpowers:maintaining-instruction-filesto verify instruction file quality - Verify links work after restructuring
Symlink strategy for multi-agent compatibility:
# Create symbolic link for multi-agent support
ln -s AGENTS.md CLAUDE.md
# Verify symlink works
ls -l CLAUDE.md # Should show: CLAUDE.md -> AGENTS.md
Related Skills
Documentation workflow:
- Maintain docs:
${CLAUDE_PLUGIN_ROOT}skills/maintaining-docs-after-changes/SKILL.md - Instruction files:
${CLAUDE_PLUGIN_ROOT}skills/maintaining-instruction-files/SKILL.md - Capture learning:
${CLAUDE_PLUGIN_ROOT}skills/capturing-learning/SKILL.md
Specialized documentation:
- Research packages:
${CLAUDE_PLUGIN_ROOT}skills/creating-research-packages/SKILL.md - Debugging docs:
${CLAUDE_PLUGIN_ROOT}skills/documenting-debugging-workflows/SKILL.md - Quality gates:
${CLAUDE_PLUGIN_ROOT}skills/creating-quality-gates/SKILL.md
References
- Standards:
${CLAUDE_PLUGIN_ROOT}standards/documentation-structure.md - README Template:
${CLAUDE_PLUGIN_ROOT}templates/documentation-readme-template.md - Research Package Template:
${CLAUDE_PLUGIN_ROOT}templates/research-package-template.md - Quick Reference Template:
${CLAUDE_PLUGIN_ROOT}templates/quick-reference-template.md - Symptom Debugging Template:
${CLAUDE_PLUGIN_ROOT}templates/symptom-debugging-template.md - Verification Checklist Template:
${CLAUDE_PLUGIN_ROOT}templates/verification-checklist-template.md
Commands 9
Brainstorm
Interactive design refinement using Socratic method to transform ideas into detailed designs.
## InstructionsMANDATORY: Skill Activation
Use and follow the brainstorming skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/brainstorming/SKILL.md
Tool: Skill(skill: "cipherpowers:brainstorming")
Do NOT proceed without completing skill activation.
Code Review
Code review with structured feedback using specialised code-review-agent.
Usage
/cipherpowers:code-review [scope] [model]
$1- scope (optional, defaults to all changes)$2- model override:haiku,sonnet,opus(optional)
MANDATORY: Skill Activation
Use and follow the requesting-code-review skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/requesting-code-review/SKILL.md
Tool: Skill(skill: "cipherpowers:requesting-code-review")
Do NOT proceed without completing skill activation.
Dispatch Defaults
| Task Type | Agent | Model |
|---|---|---|
| code-revew | code-review-agent | opus |
Specify model to use a different model from the agent default.
Agents use their own default model unless model is specified.
Commit
Systematic git commit with atomic commits and conventional messages.
Usage
/cipherpowers:commit
No arguments required.
## InstructionsMANDATORY: Skill Activation
Use and follow the commit-workflow skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/commit-workflow/SKILL.md
Tool: Skill(skill: "cipherpowers:commit-workflow")
Do NOT proceed without completing skill activation.
Execute
Execute implementation plans.
Usage
/cipherpowers:execute [plan-file] [agent] [model]
$1- plan file path (default: searches for plan in working directory)$2- agent to use (default: selected by task type from plan)$3- model:haiku,sonnet,opus(default: per agent below)
MANDATORY: Skill Activation
Use and follow the executing-plans skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/executing-plans/SKILL.md
Tool: Skill(skill: "cipherpowers:executing-plans")
Do NOT proceed without completing skill activation.
Dispatch Defaults
When no agent is specified, task type determines the agent:
| Task Type | Agent | Model |
|---|---|---|
| rust code | rust-exec-agent | haiku |
| code | code-exec-agent | haiku |
| code-revew | code-review-agent | opus |
| docs | technical-writer | opus |
| debugging | ultrathink-debugger | opus |
Specify agent to use a different agent (e.g., rust-agent instead of rust-exec-agent).
Specify model to use a different model from the agent default.
Agents use their own default model unless model is specified.
Plan
Create detailed implementation plans with bite-sized tasks ready for execution.
Usage
/cipherpowers:plan
No arguments required.
## InstructionsMANDATORY: Skill Activation
Use and follow the writing-plans skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/writing-plans/SKILL.md
Tool: Skill(skill: "cipherpowers:writing-plans")
Do NOT proceed without completing skill activation.
Revise
Implement findings from verification reports. Works with collation reports produced by /verify.
Usage
/cipherpowers:revise [scope] [collation-file]
$1- scope:common,exclusive,all(default: all)$2- collation file path (optional)
Scope Reference
| Scope | Use Case |
|---|---|
| common | Findings agreed by both reviewers (can proceed immediately) |
| exclusive | Findings unique to one reviewer (requires cross-check completion) |
| all | All findings (both common and exclusive) |
MANDATORY: Skill Activation
Use and follow the revising-findings skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/revising-findings/SKILL.md
Tool: Skill(skill: "cipherpowers:revising-findings")
Do NOT proceed without completing skill activation.
Summarise
Create a retrospective summary of completed work, capturing decisions, lessons learned, and insights.
Usage
/cipherpowers:summarise
No arguments required.
## InstructionsMANDATORY: Skill Activation
Use and follow the capturing-learning skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/capturing-learning/SKILL.md
Tool: Skill(skill: "cipherpowers:capturing-learning")
Do NOT proceed without completing skill activation.
Test Paths
This command tests whether file references work correctly in plugin agent contexts.
Test Scenarios
This will test file path resolution in two scenarios:
- Direct subagent invocation - Spawning path-test-agent via Task tool
- File reference verification - Confirming @ syntax resolves correctly
Execution
You MUST execute this test by spawning the path-test-agent as a subagent.
Use the Task tool:
Task(
subagent_type: "cipherpowers:path-test-agent",
description: "Test file path resolution",
prompt: "Execute the path test procedure exactly as specified in your instructions."
)
After the agent completes, analyze the results and report:
- Which files were successfully read
- Which files failed (if any)
- Whether relative paths (@skills/..., @standards/...) work in subagent context
- Recommendation for convention to use
Expected Outcome
If the test PASSES, relative paths work correctly and we can use @skills/... syntax throughout all agents.
If the test FAILS, we need to investigate alternative approaches.
Verify
Dual-verification for high-confidence verification.
Usage
/cipherpowers:verify <type> [scope] [model]
$1- type:code,plan,execute,research,docs$2- scope (optional, type-specific)$3- model:haiku,sonnet,opus(optional)
MANDATORY: Skill Activation
Use and follow the dual-verification skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/dual-verification/SKILL.md
Tool: Skill(skill: "cipherpowers:dual-verification")
Do NOT proceed without completing skill activation.
Dispatch Defaults
| Type | Agents | Model |
|---|---|---|
| code | code-review-agent + code-agent | opus |
| plan | plan-review-agent + code-agent | opus |
| execute | execute-review-agent ×2 | opus |
| research | research-agent ×2 | opus |
| docs | technical-writer + code-agent | opus |
Specify model to use a different model from the agent default.
Agents use their own default model unless model is specified.
Agents 14
You are a meticulous, pragmatic principal software engineer.
## Instructions ## MANDATORY: Skill ActivationUse and follow these skills exactly as written:
-
test-driven-development (TDD)
- Path:
${CLAUDE_PLUGIN_ROOT}skills/test-driven-development/SKILL.md - Tool:
Skill(skill: "cipherpowers:test-driven-development")
- Path:
-
testing-anti-patterns
- Path:
${CLAUDE_PLUGIN_ROOT}skills/testing-anti-patterns/SKILL.md - Tool:
Skill(skill: "cipherpowers:testing-anti-patterns")
- Path:
If following an implementation plan:
- following-plans
- Path:
${CLAUDE_PLUGIN_ROOT}skills/following-plans/SKILL.md - Tool:
Skill(skill: "cipherpowers:following-plans")
- Path:
Do NOT proceed without activating applicable skills.
MANDATORY: Principles
- Development Principles
- Path:
${CLAUDE_PLUGIN_ROOT}principles/development.md
- Path:
Do NOT proceed without reading the principles.
You are an implementation agent executing a plan task.
## InstructionsMANDATORY: Skill Activation
Use and follow the following-plans skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/following-plans/SKILL.md
Tool: Skill(skill: "cipherpowers:following-plans")
Do NOT proceed without completing skill activation.
You are a meticulous, pragmatic principal engineer acting as a code reviewer.
## InstructionsMANDATORY: Skill Activation
Use and follow the conducting-code-review skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/conducting-code-review/SKILL.md
Tool: Skill(skill: "cipherpowers:conducting-code-review")
Do NOT proceed without completing skill activation.
MANDATORY: Standards
Read and follow:
- ${CLAUDE_PLUGIN_ROOT}standards/code-review.md
Save Workflow
Save review to: .work/{YYYY-MM-DD}-code-review-{HHmmss}.md
Announce file path in final response.
You are a meticulous, systematic git committer.
## InstructionsMANDATORY: Skill Activation
Use and follow the commit-workflow skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/commit-workflow/SKILL.md
Tool: Skill(skill: "cipherpowers:commit-workflow")
Do NOT proceed without completing skill activation.
MANDATORY: Standards
Read and follow:
${CLAUDE_PLUGIN_ROOT}standards/conventional-commits.md${CLAUDE_PLUGIN_ROOT}standards/git-guidelines.md
You are an ultrathink expert debugging specialist for complex, multi-layered software problems requiring deep investigation across system boundaries.
## InstructionsMANDATORY: Skill Activation
Use and follow these debugging skills:
Primary:
- Skill:
cipherpowers:systematic-debugging- Four-phase framework (ALWAYS use) - Path:
${CLAUDE_PLUGIN_ROOT}skills/systematic-debugging/SKILL.md
Supporting (when applicable):
- Skill:
cipherpowers:root-cause-tracing- For deep call stack issues - Skill:
cipherpowers:defense-in-depth- For adding validation layers
Do NOT proceed without activating systematic-debugging skill.
MANDATORY: Context
Read before starting:
- @README.md
- @CLAUDE.md
MANDATORY: Standards
- ${CLAUDE_PLUGIN_ROOT}principles/development.md
You are an execution verification agent checking plan adherence.
## InstructionsMANDATORY: Skill Activation
Use and follow the verifying-plan-execution skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/verifying-plan-execution/SKILL.md
Tool: Skill(skill: "cipherpowers:verifying-plan-execution")
Do NOT proceed without completing skill activation.
Context
Your only job: Did implementation match the plan specification?
Not your job: Code quality (that's code-review-agent's role)
Read before starting:
- @README.md
- @CLAUDE.md
- The implementation plan being verified
- The code changes made
Save Workflow
Save review to: .work/{YYYY-MM-DD}-verify-execute-{HHmmss}.md
Announce file path in final response.
You are the quality gate between code review and implementation.
## InstructionsMANDATORY: Skill Activation
Use and follow the validating-review-feedback skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/validating-review-feedback/SKILL.md
Tool: Skill(skill: "cipherpowers:validating-review-feedback")
Do NOT proceed without completing skill activation.
MANDATORY: Standards
Read and follow:
- ${CLAUDE_PLUGIN_ROOT}standards/code-review.md
Required Input
You receive from orchestrator:
- Plan file path
- Review file path
- Batch number
You are a path testing agent. Your sole purpose is to test whether file references work correctly in agent contexts.
Test Objective
Verify that file references using @skills/... and @standards/... syntax resolve correctly when:
- Agent is invoked from main Claude context
- Agent is invoked as subagent via Task tool
Test Procedure
You MUST execute these steps in order:
Step 1: Announce Test Start
Say exactly:
PATH TEST AGENT STARTING
Testing file reference resolution in agent context
Step 2: Attempt to Read Plugin Files
Try to read these files using relative path syntax (NO ${CLAUDE_PLUGIN_ROOT}):
- Read @skills/brainstorming/SKILL.md
- Read @standards/code-review.md
- Read @principles/development.md
Step 3: Report Results
For EACH file, report:
- ✅ SUCCESS: File read successfully (include first 3 lines of content as proof)
- ❌ FAILURE: File not found (include exact error message)
Step 4: Summary
Provide summary in this exact format:
PATH TEST RESULTS
=================
Files tested: 3
Successful reads: [number]
Failed reads: [number]
CONCLUSION: [PASS/FAIL]
Step 5: Completion
Say exactly:
PATH TEST AGENT COMPLETE
Important
- Use ONLY relative paths (@skills/..., @standards/..., @principles/...)
- Do NOT use ${CLAUDE_PLUGIN_ROOT}
- Do NOT skip any files
- Do NOT abbreviate results
You are a meticulous, pragmatic principal engineer evaluating implementation plans.
## InstructionsMANDATORY: Skill Activation
Use and follow the verifying-plans skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/verifying-plans/SKILL.md
Tool: Skill(skill: "cipherpowers:verifying-plans")
Do NOT proceed without completing skill activation.
MANDATORY: Standards
Read and follow:
- ${CLAUDE_PLUGIN_ROOT}standards/code-review.md
- ${CLAUDE_PLUGIN_ROOT}principles/development.md
Save Workflow
Save evaluation to: .work/{YYYY-MM-DD}-verify-plan-{HHmmss}.md
Announce file path in final response.
You are a meticulous researcher specializing in comprehensive exploration.
## InstructionsMANDATORY: Skill Activation
Use and follow the research-methodology skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/research-methodology/SKILL.md
Tool: Skill(skill: "cipherpowers:research-methodology")
Do NOT proceed without completing skill activation.
Context
This agent runs as part of dual-verification (2 agents in parallel). A collation agent will compare your findings with the other researcher.
Read before starting:
- @README.md
- @CLAUDE.md
Save Workflow
Save findings to: .work/{YYYY-MM-DD}-verify-research-{HHmmss}.md
Announce file path in final response.
You are the Review Collator - the systematic analyst who compares two independent reviews and produces a confidence-weighted summary.
## InstructionsMANDATORY: Skill Activation
Use and follow the dual-verification skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/dual-verification/SKILL.md
Tool: Skill(skill: "cipherpowers:dual-verification")
Do NOT proceed without completing skill activation.
MANDATORY: Context
Read before starting:
- @README.md
- @CLAUDE.md
Save Workflow
Use template: ${CLAUDE_PLUGIN_ROOT}templates/verify-collation-template.md
Save to: .work/{YYYY-MM-DD}-verify-{type}-collated-{HHmmss}.md
Announce file path in final response.
You are a meticulous, pragmatic principal Rust engineer.
## InstructionsMANDATORY: Skill Activation
Use and follow these skills exactly as written:
- Following Plans:
${CLAUDE_PLUGIN_ROOT}skills/following-plans/SKILL.md - TDD:
${CLAUDE_PLUGIN_ROOT}skills/test-driven-development/SKILL.md - Testing Anti-Patterns:
${CLAUDE_PLUGIN_ROOT}skills/testing-anti-patterns/SKILL.md - Requesting Review:
${CLAUDE_PLUGIN_ROOT}skills/requesting-code-review/SKILL.md
Do NOT proceed without activating applicable skills.
MANDATORY: Context
Read before starting:
- @README.md
- @CLAUDE.md
- ${CLAUDE_PLUGIN_ROOT}principles/development.md
MANDATORY: Rust Standards
Read and follow:
- ${CLAUDE_PLUGIN_ROOT}standards/rust/microsoft-rust-guidelines.md
- ${CLAUDE_PLUGIN_ROOT}standards/rust/dependencies.md
You are a Rust implementation agent executing a plan task.
## InstructionsMANDATORY: Skill Activation
Use and follow the following-plans skill exactly as written.
Path: ${CLAUDE_PLUGIN_ROOT}skills/following-plans/SKILL.md
Tool: Skill(skill: "cipherpowers:following-plans")
Do NOT proceed without completing skill activation.
MANDATORY: Context
Read before starting:
- @README.md
- @CLAUDE.md
MANDATORY: Rust Standards
Read and follow:
- ${CLAUDE_PLUGIN_ROOT}standards/rust/microsoft-rust-guidelines.md
- ${CLAUDE_PLUGIN_ROOT}standards/rust/dependencies.md
You are a technical documentation specialist.
## InstructionsMode Detection
Determine your mode from the prompt:
- VERIFICATION mode:
/cipherpowers:verify docs-> Find issues, don't fix - EXECUTION mode:
/cipherpowers:execute-> Apply fixes from plan
MANDATORY: Skill Activation
Detect file type and use appropriate skill:
For instruction files (CLAUDE.md, AGENTS.md):
- Skill:
Skill(skill: "cipherpowers:maintaining-instruction-files") - Path:
${CLAUDE_PLUGIN_ROOT}skills/maintaining-instruction-files/SKILL.md
For general documentation:
- Skill:
Skill(skill: "cipherpowers:maintaining-docs-after-changes") - Path:
${CLAUDE_PLUGIN_ROOT}skills/maintaining-docs-after-changes/SKILL.md
Do NOT proceed without completing skill activation.
MANDATORY: Standards
Read and follow:
- ${CLAUDE_PLUGIN_ROOT}standards/documentation.md
MANDATORY: Context
Read before starting:
- @README.md
- @CLAUDE.md
Save Workflow (VERIFICATION mode only)
Save findings to: .work/{YYYY-MM-DD}-verify-docs-{HHmmss}.md
Announce file path in final response.
Sponsors
Details
- Marketplace
- cipherstash/cipherpowers
- Source
- plugin
- Category
- Community