# Incitaciones — Full Content for LLMs

This file contains everything an LLM needs to understand, use, and extend
the incitaciones prompt library in a single fetch.

---

## Project Overview

# Incitaciones 🤖

A collection of reusable prompts and best practices for CLI LLM tools.

## Install

Clone and install prompts as skills for Claude Code, Amp, Gemini CLI, and other tools:

```bash
git clone https://github.com/charly-vibes/incitaciones.git
cd incitaciones
./install.sh
```

**Install options:**

```bash
./install.sh --bundle essentials   # Core prompts only (7 prompts)
./install.sh --bundle planning     # Planning workflows (8 prompts)
./install.sh --bundle reviews      # Review prompts (9 prompts)
./install.sh --bundle documentation # Documentation tools (4 prompts)
./install.sh --format commands     # Legacy flat-file format for other tools
./install.sh --list                # Show available prompts
./install.sh --help                # Show all options
```

**After installation:**
```
/commit           # Deliberate commit workflow
/debug            # Systematic debugging
/create-plan      # Create implementation plans
/code-review      # Iterative code review
```

Skills are installed to `~/.agents/skills/` and copied to tool-specific directories (Claude Code, Amp, Gemini CLI, Cursor, Windsurf, Zed) when detected.

## Quick Start

```bash
# Browse content
ls content/

# Find prompts about a topic
just find refactoring

# Create new prompt
just new prompt "Your Task Name"

# Interactive search with fzf
just search
```

## Structure

Everything lives in `content/` with descriptive filenames:

- `prompt-*.md` - Reusable prompts
- `research-*.md` - Experiments and findings
- `example-*.md` - Real-world examples
- `template-*.md` - Templates for new content

See [AGENTS.md](AGENTS.md) for detailed structure and [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Commands

```bash
just --list              # Show all commands
just new [type] [name]   # Create new content
just find [term]         # Search content
just search              # Interactive fzf search
just validate            # Check metadata
just stats               # Show statistics

# Skills installation
just install             # Install prompts as ~/.claude/skills
just list-distilled      # List all distilled prompts
just validate-distilled  # Validate distilled prompts
just list-bundles        # Show available bundles
just generate-skill NAME # Preview SKILL.md output for a prompt
```

---

## Meta Prompt for LLMs

> **Use this prompt when asking other LLMs to help you organize prompts in your projects**

```
I want to organize prompts and AI instructions for my project. Please help me set up a system based on these principles:

STRUCTURE:
- Single flat directory (e.g., "prompts/" or ".ai/")
- Slugified filenames with type prefixes:
  - prompt-task-{name}.md for specific tasks
  - prompt-system-{name}.md for agent configurations
  - prompt-workflow-{name}.md for multi-step processes
  - instructions-{context}.md for project-specific instructions

METADATA:
Every file should have YAML frontmatter:
---
title: Human Readable Title
type: prompt|instruction|workflow
tags: [relevant, searchable, tags]
tools: [claude-code, cursor, aider]
status: draft|tested|verified
created: YYYY-MM-DD
updated: YYYY-MM-DD
version: 1.0.0
related: [other-file.md]
source: where-this-came-from
---

CONTENT STRUCTURE:
1. ## When to Use - Context for applying this prompt
2. ## The Prompt - The actual prompt text in a code block
3. ## Example - At least one concrete usage example
4. ## Expected Results - What success looks like
5. ## Variations - Alternative approaches
6. ## References - Links to sources or research
7. ## Notes - Caveats or additional context

WORKFLOW:
1. Create content from templates
2. Test with real AI tools
3. Update status: draft → tested → verified
4. Link related files in frontmatter
5. Track changes in CHANGELOG.md

AUTOMATION:
Create a justfile or Makefile with commands:
- new: Create from template
- find: Search by tag or keyword
- search: Interactive fzf browser
- validate: Check metadata completeness
- stats: Show repository statistics

Please analyze my project at [path] and:
1. Propose which existing prompts/instructions to capture
2. Suggest an appropriate directory name
3. Create initial template files
4. Set up basic automation commands
5. Draft 2-3 initial prompt files based on current usage

Focus on simplicity and discoverability over complex organization.
```

## Examples

**Creating a new task prompt:**
```bash
just new prompt "Incremental Refactoring"
# Edit content/prompt-task-incremental-refactoring.md
# Add frontmatter, prompt text, examples
# Test it with Claude Code
# Mark as tested and commit
```

**Finding related content:**
```bash
just find refactoring
# Shows all files tagged with 'refactoring'

just search
# Opens fzf to interactively browse and preview content
```

**Validating content:**
```bash
just validate
# Checks all files have required metadata
# Verifies related files exist
# Reports any issues
```

## What Goes Here?

✅ **Good candidates:**
- Prompts you use repeatedly
- Task patterns that work well
- Tool-specific configurations
- Research on what works
- Real examples of successful interactions

❌ **Don't include:**
- Project-specific code
- Sensitive information
- One-off experiments without documentation
- Incomplete drafts without context

## Philosophy

**Flat structure** - One directory, easy to find everything
**Rich metadata** - Searchable, relatable, trackable
**Tested content** - Everything should have real usage examples
**Source attribution** - Credit where ideas come from
**Version control** - Track evolution of prompts over time

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for:
- File naming conventions
- Metadata requirements
- Quality standards
- Submission process

## Tools

This repository is designed to work with:
- **Claude Code** - Anthropic's CLI
- **Aider** - AI pair programming
- **Cursor** - AI-first editor
- **Gemini CLI** - Google's CLI
- Any other LLM CLI tool

The prompts are tool-agnostic where possible, with tool-specific variations noted.

## License

[To be determined]

## Related Projects

- [Awesome Prompts](https://github.com/f/awesome-chatgpt-prompts)
- [Anthropic Prompt Library](https://docs.anthropic.com/claude/prompt-library)
- [OpenAI Prompt Engineering Guide](https://platform.openai.com/docs/guides/prompt-engineering)


---

## A note on authorship

All the code in this repository was generated by a large language model. This is not a confession, nor an apology. It's a fact, like the one that says water boils at a hundred degrees at sea level: neutral, technical, and with consequences one discovers later.

What the human did is what tends to happen before and after things come into existence: thinking. Reviewing requirements, arguing about edge cases, understanding what needs to be built and why, deciding how the system should behave when reality —which is capricious and does not read documentation— confronts it with situations nobody anticipated. The hours of planning, of design, of reading specifications until exhaustion dissolves the boundary between understanding and hallucination.

The LLM writes. The human knows what it should say.

There is a distinction, even if looking at the commit history makes it hard to find. The distinction is that a machine can produce correct code without understanding anything, the same way a calculator can solve an integral without knowing what time is. Understanding what that integral is *for*, whether it actually solves the problem, whether the problem was the right problem to begin with — that remains human territory. For now.

*[Leer en español](https://charly-vibes.github.io/charly-vibes/)*


---

## How to Create a New Prompt

### Contributing Guidelines (structure & quality standards)

# Contributing to Incitaciones

Thank you for contributing! This guide will help you add content that's useful, well-documented, and discoverable.

## Quick Start

```bash
# Create new content
just new prompt "Your Prompt Name"
just new research "Your Research Topic"
just new example "Your Example Description"

# Validate before committing
just validate

# Update changelog
just changelog "Added prompt for X"

# Commit
git add content/ CHANGELOG.md
git commit -m "Add prompt for X"
```

## File Naming Conventions

All files use slugified names with type prefixes:

### Prompts

- `prompt-task-{name}.md` - Task-specific prompts
- `prompt-system-{name}.md` - System configurations
- `prompt-workflow-{name}.md` - Multi-step workflows
- `prompt-tool-{tool}-{name}.md` - Tool-specific prompts

**Examples:**
- `prompt-task-incremental-refactoring.md`
- `prompt-system-coding-assistant.md`
- `prompt-workflow-git-commit-process.md`
- `prompt-tool-claude-code-hooks.md`

### Research

- `research-paper-{title}.md` - Paper summaries
- `research-experiment-{topic}.md` - Experiments and tests
- `research-finding-{topic}.md` - Insights and patterns
- `research-benchmark-{topic}.md` - Performance comparisons

**Examples:**
- `research-paper-chain-of-thought.md`
- `research-experiment-prompt-length.md`
- `research-finding-temperature-settings.md`

### Examples

- `example-{description}.md` - Any type of real-world example

**Examples:**
- `example-refactoring-auth-system.md`
- `example-debugging-memory-leak.md`
- `example-conversation-complex-workflow.md`

### References

- `references-{category}.md` - Collections of links

**Examples:**
- `references-papers.md`
- `references-tools.md`
- `references-articles.md`

## Required Metadata

Every file must have YAML frontmatter with these required fields:

```yaml
---
title: Human Readable Title
type: prompt|research|example|references
tags: [at, least, three, tags]
status: draft|tested|verified
created: YYYY-MM-DD
version: 1.0.0
---
```

### Optional but Recommended

```yaml
tools: [claude-code, aider, cursor, gemini]
related: [other-file.md, another-file.md]
source: original|adapted-from-URL|research-based
author: your-name
difficulty: beginner|intermediate|advanced
```

## Content Structure Standards

### For Prompts

Must include:

1. **When to Use** - Context and situations
2. **The Prompt** - The actual prompt in a code block
3. **Example** - At least one concrete usage
4. **Expected Results** - What success looks like
5. **References** - Sources and inspiration

Optional:
- **Variations** - Alternative approaches
- **Notes** - Caveats and tips

### For Research

Must include:

1. **Summary** - 2-3 sentences
2. **Context** - Why this was investigated
3. **Method** - How you tested/studied
4. **Results** - What you found
5. **Practical Applications** - How to use this
6. **References** - Source material

### For Examples

Must include:

1. **Context** - Starting situation
2. **Goal** - What you were trying to do
3. **Process** - Step-by-step walkthrough
4. **Results** - Final outcome
5. **Lessons Learned** - Key insights

## Status Progression

Content should progress through these stages:

### draft

- Initial version
- Not yet tested in real scenarios
- May have incomplete sections
- Ready for feedback

### tested

- Successfully used at least once
- All sections completed
- Examples verified to work
- Ready for broader use

### verified

- Multiple successful uses
- Peer-reviewed or validated by others
- Well-documented edge cases
- Production-ready

Update status with:
```bash
just mark-tested content/prompt-task-example.md
just mark-verified content/prompt-task-example.md
```

## Quality Checklist

Before submitting, ensure:

- [ ] All required metadata fields present
- [ ] At least 3 relevant tags
- [ ] Clear, descriptive title
- [ ] Concrete example included
- [ ] Source attribution if adapted
- [ ] Related files linked (minimum 2 if available)
- [ ] Status reflects actual testing
- [ ] CHANGELOG.md updated
- [ ] No typos or formatting issues

Run validation:
```bash
just validate
just check-links
```

## Relating Content

Link related files in the frontmatter:

```yaml
---
related:
  - prompt-task-testing.md
  - research-finding-safe-refactoring.md
  - example-auth-refactoring.md
---
```

Guidelines:
- Link at least 2 related files (if available)
- Link prompts to research that informed them
- Link examples to prompts they demonstrate
- Link research to prompts it supports

## Source Attribution

Always credit where ideas come from:

```yaml
source: original                           # Your own work
source: adapted-from-anthropic-docs        # Modified from existing
source: https://example.com/article        # Direct link to source
source: research-paper-chain-of-thought.md # Based on research in repo
```

In the content, cite sources:

```markdown
## References

- [Original Article](https://example.com) - Inspiration for this approach
- Martin Fowler's "Refactoring" - Methodology basis
- research-finding-safe-patterns.md - Supporting research
```

## Versioning

Use semantic versioning:

- **Patch** (1.0.0 → 1.0.1) - Typo fixes, minor clarifications
- **Minor** (1.0.0 → 1.1.0) - Add variations, improve examples, expand content
- **Major** (1.0.0 → 2.0.0) - Significant changes to the prompt itself, breaking changes

Update version in frontmatter:
```yaml
version: 1.1.0
updated: 2026-01-12
```

Add to version history section:
```markdown
## Version History

- 1.1.0 (2026-01-12): Added variations for high-risk code
- 1.0.0 (2026-01-10): Initial version
```

## Testing Requirements

### For Prompts

Before marking as "tested":
1. Use the prompt with at least one real AI tool
2. Verify it produces expected results
3. Document actual usage in the Example section
4. Note any surprises or edge cases in Notes

Before marking as "verified":
1. Multiple successful uses (at least 3)
2. Tested by someone other than author (if possible)
3. Edge cases documented
4. Variations tested

### For Research

Before marking as "tested":
1. Experiment completed with documented results
2. Data or examples collected
3. Analysis written

Before marking as "verified":
1. Findings replicated or confirmed
2. Practical applications identified
3. Related prompts updated to use findings

### For Examples

All examples should be "verified" by default:
1. Based on real usage
2. Outcomes accurately documented
3. Code/artifacts available if possible

## Changelog Updates

Always update CHANGELOG.md when adding or modifying content:

```bash
just changelog "Added prompt for incremental refactoring"
just changelog "Updated research on temperature settings"
just changelog "Fixed typo in debugging example"
```

Or manually add under `## [Unreleased]`:

```markdown
## [Unreleased]

### 2026-01-12

- Added prompt for incremental refactoring
- Updated research on temperature settings with new findings
- Fixed typo in debugging example
```

## Commit Guidelines

### Conventional Commit Format

We use detailed conventional commits to track not just what changed, but the context in which it was created or tested.

```
<type>(<scope>): <description>

<detailed body>

Tool: <tool-name>
Model: <model-name>
Status: <draft|tested|verified>
Context: <optional context>
```

**Types:**
- `add` - New content
- `update` - Changes to existing content
- `fix` - Corrections or bug fixes
- `docs` - Documentation changes
- `meta` - Repository maintenance
- `test` - Testing existing content
- `refactor` - Restructuring without changing meaning

**Scopes:**
- `prompt` - Prompt files
- `research` - Research files
- `example` - Example files
- `template` - Template files
- `workflow` - Workflow and automation
- `docs` - Documentation files

### Metadata in Commits

Always include in the commit body:

- **Tool:** The AI CLI tool used (claude-code, aider, cursor, gemini, etc.)
- **Model:** The specific model (claude-sonnet-4.5, gpt-4, gemini-pro, etc.)
- **Status:** The status of the content (draft, tested, verified)
- **Context:** (Optional) Additional context like project type, use case, etc.

### Examples

**Adding new prompt:**
```
add(prompt): incremental refactoring with safety checks

Added task prompt for safe refactoring with test checkpoints between
each change. Includes variations for high-risk code and code without
existing test coverage.

Tool: claude-code
Model: claude-sonnet-4.5
Status: tested
Context: Used on TypeScript refactoring project with Jest tests
```

**Updating research:**
```
update(research): temperature settings for different tasks

Extended temperature experiment with new findings from creative vs
structured tasks. Found that 0.7 works better for brainstorming while
0.3 is optimal for code generation.

Tool: claude-code, aider
Model: claude-sonnet-4.5, gpt-4
Status: verified
Context: Tested across 15 different task types
```

**Fixing issues:**
```
fix(prompt): correct git workflow example commands

Fixed broken git commands in workflow example that were using wrong
branch names. Updated to use 'main' instead of 'master'.

Tool: claude-code
Model: claude-sonnet-4.5
Status: verified
```

**Adding examples:**
```
add(example): debugging memory leak in Node.js app

Real-world example of using debugging prompts to identify and fix
memory leak. Shows full interaction including false starts and
eventual solution.

Tool: cursor
Model: claude-sonnet-4.5
Status: verified
Context: Express.js app with 100k+ requests/day
```

**Documentation updates:**
```
docs(contributing): add conventional commit guidelines

Extended commit guidelines to include metadata about tools and models
used. This helps track which tools work best for different types of
prompts.

Tool: claude-code
Model: claude-sonnet-4.5
Status: n/a
```

### Why Detailed Commits?

Including tool and model information helps us:

1. **Track effectiveness** - See which models excel at different tasks
2. **Version compatibility** - Know if prompts need updates for new models
3. **Tool optimization** - Identify tool-specific patterns and best practices
4. **Research value** - Build a dataset of what works across different tools
5. **Reproducibility** - Others can replicate with same setup

### Quick Commit Template

Create a git commit template:

```bash
# ~/.gitmessage
<type>(<scope>): <description>

# Detailed description of changes

Tool:
Model:
Status:
Context:
```

Enable it:
```bash
git config --local commit.template ~/.gitmessage
```

### What to Commit Together

Group related changes:

```bash
# Adding new prompt
git add content/prompt-task-new-feature.md CHANGELOG.md
git commit -m "add: new feature implementation prompt"

# Updating prompt and related research
git add content/prompt-task-refactoring.md content/research-finding-patterns.md CHANGELOG.md
git commit -m "update: refactoring prompt with new research findings"
```

## Style Guidelines

### Writing Style

- **Clear and concise** - Get to the point quickly
- **Active voice** - "Use this prompt when..." not "This prompt can be used when..."
- **Specific examples** - Concrete is better than abstract
- **Actionable** - Tell users exactly what to do

### Formatting

- Use code blocks for prompts and examples
- Use bullet lists for multiple points
- Use **bold** for emphasis (sparingly)
- Use `code` for commands, filenames, and technical terms
- Use > blockquotes for important notes

### Technical Terms

- Be consistent with terminology
- Define specialized terms on first use
- Use standard industry terms when available
- Link to definitions or documentation when helpful

## Common Mistakes to Avoid

❌ **Don't:**
- Create files without testing them
- Use vague or generic titles
- Skip source attribution
- Forget to link related content
- Leave metadata fields empty
- Add files without updating CHANGELOG

✅ **Do:**
- Test prompts before submitting
- Use descriptive, searchable titles
- Credit sources and inspirations
- Link to 2+ related files
- Fill all required metadata
- Update CHANGELOG with every change

## Getting Help

If you're unsure about:

- **Structure** - Check existing files as examples
- **Naming** - Use `just find` to see similar content
- **Metadata** - Run `just validate` to check requirements
- **Quality** - Review AGENTS.md for philosophy

## Review Process

1. **Self-review** - Check against this guide
2. **Validate** - Run `just validate` and `just check-links`
3. **Test** - Actually use the content with real tools
4. **Submit** - Create PR or commit directly (if authorized)
5. **Update** - Address feedback and mark as tested/verified

## Philosophy Reminder

Remember the repository goals:

- **Quality over quantity** - One great prompt beats ten mediocre ones
- **Evidence-based** - Every claim should have supporting examples
- **Discoverable** - Rich metadata makes content findable
- **Evolving** - Update based on real usage and feedback
- **Shared learning** - Document both successes and failures

---

Thank you for contributing! Your shared knowledge helps the entire community build better AI workflows.


---

### Prompt Template

---
title: [Human Readable Title]
type: prompt
tags: [tag1, tag2, tag3]
tools: [claude-code, aider, cursor, gemini]
status: draft
created: [YYYY-MM-DD]
updated: [YYYY-MM-DD]
version: 1.0.0
related: []
source: [original|adapted-from-URL|research-based]
---

# [Title]

## When to Use

[Describe the context and situations where this prompt is most effective. Be specific about:
- What problem it solves
- When NOT to use it
- Prerequisites or requirements]

## The Prompt

> **Note:** Use 4 backticks (```````` ) for the outer code fence when your prompt
> contains nested code blocks. This prevents early termination during extraction.

````
[The actual prompt text that will be given to the AI tool.
Be clear, specific, and actionable.
Include any necessary context or constraints.

If your prompt includes code examples, use standard triple backticks:
```language
// example code
```
]
````

## Example

**Context:**
[Briefly describe the scenario]

**Input:**
```
[What you actually type or paste to the AI tool]
```

**Expected Output:**
```
[What the AI should produce or do]
```

## Expected Results

- [Bullet point of what success looks like]
- [What the AI should deliver]
- [How you can verify it worked]

## Variations

**For [specific context]:**
```
[Modified version of the prompt]
```

**Alternative approach:**
```
[Different way to achieve similar results]
```

## References

- [Link to source material, research, or inspiration]
- [Related articles or documentation]
- [Community discussions or examples]

## Notes

[Additional context, caveats, tips, or warnings.
Things learned from using this prompt in practice.]

## Version History

- 1.0.0 ([YYYY-MM-DD]): Initial version


---

## All Distilled Prompts

These are the token-optimized versions ready for direct use as skills.

### Standalone Specification Review (Rule of 5) — Iterative review of technical specifications for autonomy, precision, and AI-readiness

> Skill name: `specification-review`

# Standalone Specification Review (Rule of 5)

Perform thorough technical specification review using the Rule of 5 - iterative refinement until convergence.

## Setup
**If spec path provided:** Read the specification completely
**If no path:** Ask for path or list available specs from `specs/` or `openspec/`

## Process
Perform 5 passes. After each (starting with pass 2), check for convergence.

---

### PASS 1 - Standalone Integrity & Amnesia Test
**Focus:**
- **Amnesia Test:** Stateless agent execution using ONLY this file + codebase.
- **Rationale:** Strategic "Why" (problem link) present.
- **Encapsulation:** External schemas/types explicitly path-referenced.
- **Metadata:** Unique `change-id` and versioning.

**Format:**
```
[INT-001] [CRITICAL|HIGH|MEDIUM|LOW] - [Section]
Description: [What's missing/disconnected]
Impact: [Why this violates Amnesia Test]
Recommendation: [Specific path/reference fix]
```

### PASS 2 - Well-Formed Requirements (IEEE 29148)
**Focus:**
- **Singularity:** Exactly one capability per requirement.
- **Necessity:** Essential to system; no gold-plating.
- **Verifiability:** Clear proof of meeting requirement.
- **Completeness:** No "TBD" or external dependencies.

**Prefix:** SPEC-001, SPEC-002, etc.

### PASS 3 - Precision Language & Weak Words
**Focus:** Eliminate subjective language.
- **Subjective:** Fast, easy, intuitive, seamless, robust -> Use metrics.
- **Vague Quant:** Some, many, often, several, most -> Use numbers.
- **Incomplete Lists:** Etc., such as, including but not limited to -> Use exhaustive sets.
- **Vague Verbs:** Support, handle, provide, optimize, maintain -> Use "Render," "Validate," "Store."

**Prefix:** PREC-001, PREC-002, etc.

### PASS 4 - Behavioral Coverage (BDD)
**Focus:**
- **Gherkin Scenarios:** Every requirement has a GIVEN-WHEN-THEN block.
- **Happy Path:** Standard success case defined.
- **Edge Cases:** Empty states, maximum limits, boundary values (N, N+1, N-1).
- **Negative Paths:** Validation errors, network failures, permission denials.

**Prefix:** BEHV-001, BEHV-002, etc.

### PASS 5 - Executability & Interface Integrity
**Focus:**
- **Data Models:** TypeScript types/JSON schemas explicitly defined.
- **Interface Contracts:** Explicit I/O mapping for APIs/UI components.
- **Task Readiness:** Granular enough for `tasks.md` conversion.
- **Non-Goals:** Work boundaries explicitly stated.

**Prefix:** EXEC-001, EXEC-002, etc.

---

## Convergence Check
Report after each pass (starting with pass 2):
```
Convergence Check After Pass [N]:
1. New CRITICAL issues: [count]
2. Total new issues this pass: [count]
3. Total new issues previous pass: [count]
4. Estimated false positive rate: [percentage]
Status: [CONVERGED | ITERATE | NEEDS_HUMAN]
```
**CONVERGED:** No new CRITICAL, <10% new issues vs previous pass, <20% false positives.

---

## Final Report
```
## Specification Review Final Report
**Spec:** [path/to/spec.md] | **Convergence:** Pass [N]

### Summary
- CRITICAL: [count] - Blocks implementation/Amnesia Test
- HIGH: [count] - Significant ambiguity/missing scenarios
- MEDIUM: [count] - Minor precision/structural issues
- LOW: [count] - Nice to have improvements

### Top 3 Most Critical Findings
[ID] [Description] - [Location]
Impact: [Why this matters for SDD] | Fix: [Actionable step]

### Recommended Revisions
1. [Specific actionable step]
2. [Specific actionable step]
3. [Specific actionable step]

### Verdict: [READY_TO_IMPLEMENT | NEEDS_REVISION | NEEDS_REWORK]
**Rationale:** [Based on Amnesia Test]
```

## Rules
1. **Reference specific lines/sections.**
2. **Flag all vibes:** Eliminate "easy," "fast," "support," "maintain."
3. **If you can't write a test for it, it's not a spec.**
4. **Stop at convergence; don't force 5 stages.**


---

### Workflow for Deliberate Commits — Create well-structured, atomic git commits with clear intent

> Skill name: `commit`

# Commit Changes with Review

Create git commits for changes made during this session.

## CRITICAL RULES

1. **NEVER commit without describing what will be committed first**
2. **NEVER use `git add -A` or `git add .`**
3. **ALWAYS review conversation history to write accurate commit messages**
4. **ALWAYS make multiple logical commits instead of one large commit**
5. **NEVER add co-author or AI attribution** (commits authored by human only)

## Process

### Step 1: Review What Changed

```bash
# Show all changes
git status

# Review each file
git diff path/to/file1
git diff path/to/file2
```

### Step 2: Describe Changes to User

Present a structured description:

```
I've made changes to the following files:

1. src/components/Login.tsx
   - Added OAuth provider selection
   - Implemented token refresh logic
   - Added error boundary for auth failures

2. src/utils/auth.ts
   - Created validateToken helper
   - Added token expiry checking

3. tests/auth.test.ts
   - Added tests for new OAuth flow
   - Added tests for token validation

These changes can be grouped into logical commits:

Commit 1: "Add OAuth provider selection to login"
- src/components/Login.tsx
- src/utils/auth.ts

Commit 2: "Add token validation and refresh"
- src/utils/auth.ts (additional changes)
- tests/auth.test.ts

Shall I proceed with these commits?
```

### Step 3: Wait for Confirmation

**Do not proceed until the user confirms or provides guidance.**

### Step 4: Execute Commits

For each approved commit:

```bash
# Add specific files only
git add src/components/Login.tsx
git add src/utils/auth.ts

# Create commit with descriptive message
git commit -m "add(auth): OAuth provider selection in login

Added UI for selecting OAuth provider (Google, GitHub, Microsoft).
Implemented provider-specific configuration and redirect handling.

- LoginForm component now displays provider buttons
- auth.ts handles provider-specific OAuth flows
- Error states for unsupported providers"

# Verify
git log --oneline -1
```

### Step 5: Repeat for Additional Commits

Continue with remaining logical groups of changes.

## Commit Message Format

```
<type>(<scope>): <short description>

<detailed description of what and why>

- Bullet points for key changes
- Focus on the 'why' not just the 'what'
```

**Types:** add, update, fix, refactor, docs, test, chore

## Good vs Bad Commits

### ❌ Bad Approach
```bash
git add -A
git commit -m "updates"
```

### ✅ Good Approach
```bash
git add src/auth/oauth.ts
git add src/auth/providers.ts
git commit -m "add(auth): OAuth provider abstraction

Created provider interface and implementations for Google, GitHub.
Each provider handles its own authorization URLs and token exchange.

- BaseProvider interface defines contract
- GoogleProvider and GitHubProvider implementations
- Provider registry for runtime selection"
```

## Verification Checklist

Before each commit:
- [ ] Reviewed git diff for each file
- [ ] Grouped changes logically
- [ ] Written descriptive commit message with context
- [ ] Used explicit file paths in git add
- [ ] No AI attribution in commit message
- [ ] Commit message explains why, not just what


---

### Systematic Debugging with DDx — 7-step diagnostic workflow for debugging issues

> Skill name: `debug`

You are an expert systems diagnostician. We are going to apply the principles of medical differential diagnosis to debug a software issue.

**1. Symptom & Problem Representation:**
The primary symptom is: [DESCRIBE THE OBSERVED PROBLEM, e.g., "p99 latency for the /api/v1/users endpoint has spiked by 300% in the last hour."]
The system context is: [BRIEFLY DESCRIBE THE SYSTEM, e.g., "A Node.js microservice connected to a PostgreSQL database, running on Kubernetes."]

**Your Task:**
Follow this seven-step workflow:

1.  **Re-state the Problem:** Briefly summarize the problem representation in standard engineering terminology.
2.  **Generate Hypotheses (Differential Diagnosis):** List all plausible root causes for the symptom, from most likely to least likely. Do not stop at the obvious.
3.  **Define Illness Scripts:** For each of your top 3 hypotheses, describe the "illness script"—the typical narrative or pattern of how this cause would manifest.
4.  **Propose Diagnostic Tests:** For each hypothesis, propose a specific, executable test (e.g., a command, a query, a metric to check) that could be used to *conclusively rule it out*.
5.  **Simulate Results & Narrow:**
    - Assume Test #1 (for your most likely hypothesis) comes back *negative*. What does this tell you?
    - Assume Test #2 (for your second most likely hypothesis) comes back *positive*.
6.  **State the Probable Diagnosis:** Based on the simulated results, state the most likely diagnosis (root cause).
7.  **Recommend Treatment:** Propose a specific, immediate action to mitigate or fix the issue.


---

### Describe Pull Request — Generate clear PR descriptions from code changes

> Skill name: `describe-pr`

# Generate PR Description

Create a comprehensive pull request description based on the actual changes in the PR.

## Process

### Step 1: Identify the PR

**If on branch with associated PR:**
```bash
gh pr view --json url,number,title,state,baseRefName
```

**If not on PR branch or PR doesn't exist:**
```bash
# List open PRs
gh pr list --limit 10 --json number,title,headRefName,author

# Ask user which PR to describe
```

### Step 2: Gather PR Information

```bash
# Get full diff
gh pr diff {number}

# Get commit history
gh pr view {number} --json commits --jq '.commits[] | "\(.oid[0:7]) \(.messageHeadline)"'

# Get PR metadata
gh pr view {number} --json url,title,number,state,baseRefName,additions,deletions
```

### Step 3: Analyze Changes Deeply

Review all changes and understand:

**What changed:**
- Files modified, added, removed
- Lines added/removed
- Key functions/classes affected

**Why it changed:**
- What problem does this solve?
- What requirement does this fulfill?
- What was wrong before?

**Impact:**
- User-facing changes
- API changes
- Breaking changes
- Performance implications
- Security considerations

**Context:**
- Related issues
- Related plans or design docs
- Dependencies on other PRs
- Follow-up work needed

### Step 4: Generate Description

**Template:**

```markdown
## Summary

[2-3 sentence overview of what this PR does and why it's needed]

## Changes

**Key changes:**
- [Specific change 1 with reasoning]
- [Specific change 2 with reasoning]
- [Specific change 3 with reasoning]

**Files changed:**
- `path/to/file1.ext` - [What changed and why]
- `path/to/file2.ext` - [What changed and why]

## Motivation

[Explain the problem this PR solves or the requirement it fulfills.
Reference related issues, user requests, or technical debt.]

## Implementation Details

[Explain key implementation decisions, trade-offs considered,
and why this approach was chosen over alternatives.]

**Key decisions:**
1. [Decision 1]: [Rationale]
2. [Decision 2]: [Rationale]

## Related

- Issue: #123 [if applicable]
- Plan: `plans/2026-01-12-feature-name.md` [if applicable]
- Design doc: `docs/design-xyz.md` [if applicable]
- Depends on: PR #456 [if applicable]
- Blocks: PR #789 [if applicable]

## Testing

**Automated tests:**
- [ ] Unit tests pass (`npm test`)
- [ ] Integration tests pass
- [ ] E2E tests pass [if applicable]

**Manual testing:**
- [ ] [Specific manual test 1]
- [ ] [Specific manual test 2]
- [ ] [Specific manual test 3]

**Test coverage:**
- [Coverage stats if available]

## Breaking Changes

[If any breaking changes, list them prominently here with migration guidance]

**None** [if no breaking changes]

## Migration Guide

[If breaking changes exist, provide step-by-step migration instructions]

## Security Considerations

[Any security implications, or state "None identified"]

## Performance Impact

[Any performance changes, benchmarks, or state "No significant impact"]

## Screenshots / Demos

[For UI changes, include before/after screenshots or GIFs]

## Rollout Plan

[If phased rollout needed, describe the plan]

## Follow-up Work

[List any follow-up work needed in future PRs]
- [ ] [Follow-up task 1]
- [ ] [Follow-up task 2]

## Reviewer Notes

[Specific things you want reviewers to focus on or be aware of]
```

### Step 5: Present to User

Show the generated description and ask for approval:

```
I've generated a PR description for PR #{number}. Here's what I've created:

[Show description]

Would you like me to:
1. Update the PR with this description
2. Make changes to the description first
3. Copy to clipboard for manual update
```

### Step 6: Update PR

Upon approval:

```bash
# Save description to temp file (for complex descriptions with newlines)
cat > /tmp/pr-description.md <<'EOF'
[description content]
EOF

# Update PR
gh pr edit {number} --body-file /tmp/pr-description.md

# Verify
gh pr view {number}
```

## Guidelines

1. **Focus on "why" not just "what"** - Diff shows what, description explains why
2. **Be specific** - Vague descriptions aren't helpful
3. **Include context** - Link to issues, plans, discussions
4. **Think about reviewers** - What do they need to know?
5. **Highlight breaking changes** - Make them impossible to miss
6. **Provide testing guidance** - Help reviewers verify
7. **Be thorough but scannable** - Use headers and bullets


---

### Iterative Code Review — Multi-pass code review using Rule of 5 principle

> Skill name: `code-review`

# Iterative Code Review with Rule of 5

I need you to review this code using the Rule of 5 - five stages of iterative refinement.

CODE TO REVIEW:
[paste your code or specify file path]

PHILOSOPHY: "Breadth-first exploration, then editorial passes"

STAGE 1: DRAFT - Get the shape right
Question: Is the overall approach sound?
Focus:
- Don't aim for perfection
- Review overall structure and approach
- Identify major architectural issues
- Get the "shape" right before refining details
- Is this solving the right problem?

Output: High-level assessment, major structural issues

STAGE 2: CORRECTNESS - Is the logic sound?
Question: Are there errors, bugs, or logical flaws?
Focus:
- Fix errors and bugs identified in Stage 1
- Verify logical correctness
- Check algorithms and data structures
- Ensure functions do what they claim
- Identify off-by-one errors, wrong operators, etc.

Output: List of correctness issues with locations

STAGE 3: CLARITY - Can someone else understand this?
Question: Is the code comprehensible?
Focus:
- Improve readability based on Stage 2 fixes
- Remove or explain technical jargon
- Clarify variable and function names
- Improve code organization
- Add comments where intent isn't obvious

Output: Clarity improvements and naming suggestions

STAGE 4: EDGE CASES - What could go wrong?
Question: Are boundary conditions handled?
Focus:
- Identify gaps from previous stages
- Handle unusual scenarios
- Check boundary conditions (null, empty, max values)
- Error handling for external dependencies
- Input validation gaps

Output: Edge cases and error handling issues

STAGE 5: EXCELLENCE - Ready to ship?
Question: Would you be proud to ship this?
Focus:
- Final polish based on all previous stages
- Production quality check
- Performance considerations
- Documentation completeness
- Overall code quality

Output: Final recommendations for production readiness

CONVERGENCE CHECK:
After each stage (starting with Stage 2), report:
1. Number of new CRITICAL issues found
2. Number of new issues vs previous stage
3. Convergence status:
   - CONVERGED: No new CRITICAL, <10% new issues
   - CONTINUE: Proceed to next stage
   - NEEDS_HUMAN: Found blocking issues requiring judgment

FINAL REPORT:
- Total issues by severity
- Top 3 most critical findings
- Recommended next actions
- Production readiness assessment


---

### Create Implementation Plan — Design phased implementation plans with TDD approach

> Skill name: `create-plan`

# Create Implementation Plan

Create a detailed implementation plan for the requested feature.

## When Invoked

1. **If a spec file is provided**: Read it fully and begin planning
2. **If no parameters**: Ask for the feature/task description

## Process

### Step 1: Understand the Requirement

1. Read any mentioned spec files completely
2. Check existing research/documentation for related work
3. Review any previous discussions or decisions on the topic
4. Understand the scope and constraints
5. Ask clarifying questions if anything is unclear

### Step 2: Research the Codebase

**Create a todo list to track research tasks.**

1. Find relevant existing patterns and code
2. Identify integration points
3. Note conventions to follow
4. Understand the current architecture
5. Identify files that will need changes

**Use parallel research when possible:**
- Search for similar features
- Read key files that will be affected
- Check for existing tests to understand test patterns

### Step 3: Design Options (if applicable)

If multiple approaches are viable:

1. Present 2-3 design options
2. Include pros/cons for each
3. Recommend an approach (explain why)
4. Get user alignment before detailed planning

### Step 4: Write the Plan

Save to `plans/YYYY-MM-DD-description.md`:

```markdown
# [Feature Name] Implementation Plan

**Date**: YYYY-MM-DD

## Overview

[Brief description of what we're implementing]

## Related

- Spec: `specs/XX_feature.feature` (if applicable)
- Research: `research/YYYY-MM-DD-topic.md` (if applicable)
- Related issues/tickets: [references]

## Current State

[What exists now, what's missing, what needs to change]

## Desired End State

[What will exist after implementation]

**How to verify:**
- [Specific verification steps]
- [Expected behaviors]

## Out of Scope

[What we're explicitly NOT doing to prevent scope creep]

## Risks & Mitigations

[Identified risks and how we'll handle them]

## Phase 1: [Name]

### Changes Required

**File: `path/to/file.ext`**
- Changes: [Specific modifications needed]
- Tests: [What tests to write first (TDD)]

**File: `another/file.ext`**
- Changes: [Specific modifications needed]
- Tests: [What tests to write first (TDD)]

### Implementation Approach

[How we'll implement this phase - key decisions, patterns to use]

### Success Criteria

#### Automated:
- [ ] Tests pass: `npm test` (or relevant command)
- [ ] Type checking passes (if applicable)
- [ ] Linting passes (if applicable)
- [ ] Build succeeds (if applicable)

#### Manual:
- [ ] [Specific manual verification step 1]
- [ ] [Specific manual verification step 2]

### Dependencies

[Any dependencies on other work or external factors]

---

## Phase 2: [Name]

[Continue with same structure for each phase]

---

## Testing Strategy

**Following TDD:**
1. Write tests first for each behavior
2. Watch tests fail (Red)
3. Implement minimal code to pass (Green)
4. Refactor while keeping tests green

**Test types needed:**
- Unit tests: [What to unit test]
- Integration tests: [What integration scenarios]
- E2E tests: [If applicable]

## Rollback Strategy

[How to safely rollback if something goes wrong]

## Related Links

- [Related documentation]
- [Similar implementations in the codebase]
- [External resources]
```

### Step 5: Review and Iterate

1. Present the plan to the user
2. Highlight key decisions made
3. Note any areas where feedback is particularly valuable
4. Iterate based on feedback until approved

## Guidelines

1. **Be specific**: Include actual file paths and concrete changes, not vague descriptions
2. **Follow TDD**: Plan tests before implementation for each phase
3. **Break into phases**: Each phase should be independently verifiable and take <2 hours ideally
4. **Track progress**: Use todo list throughout planning process
5. **No open questions**: Resolve all questions before finalizing (use AskUserQuestion tool)
6. **Consider the user**: Plans should be readable by both humans and AI agents
7. **Be realistic**: Account for complexity, don't oversimplify

## Usage Scenarios

**Scenario 1: Feature with spec**
```
User: Create a plan for implementing user authentication based on specs/auth.feature

Agent: I'll create an implementation plan for user authentication. Let me first read the spec and research the codebase.

[Reads spec file, searches for existing auth patterns, creates todo list]

Agent: Based on the spec and codebase research, I see we need JWT-based authentication. I found existing patterns in the API middleware that we should follow. I'll create a 3-phase plan:

Phase 1: JWT token validation
Phase 2: Authentication middleware
Phase 3: Protected route integration

[Creates plan file at plans/2026-01-12-user-authentication.md]

Here's the plan I've created: [summarizes key points]

The plan follows our existing API patterns and includes TDD approach. Any feedback before we proceed?
```

**Scenario 2: No spec, just description**
```
User: I need to add pagination to the user list endpoint

Agent: I'll create a plan for adding pagination. What would you like me to document?

Let me research the codebase first to understand:
1. How other endpoints handle pagination
2. Current user list implementation
3. Database query patterns

[Creates todo list, researches in parallel]

Agent: I found that other endpoints use cursor-based pagination with the pattern from utils/pagination.ts.

I have two design options:

**Option 1: Cursor-based (Recommended)**
- Pros: Consistent with existing endpoints, handles large datasets well
- Cons: Slightly more complex client implementation

**Option 2: Offset-based**
- Pros: Simpler client implementation
- Cons: Performance issues with large offsets, inconsistent with our patterns

I recommend Option 1 for consistency. Shall I proceed with that approach?

[After confirmation, creates detailed plan]
```

**Scenario 3: Complex feature requiring exploration**
```
User: Create a plan for real-time notifications

Agent: Real-time notifications is a complex feature. Before I can create a detailed plan, I need to research several technical decisions:

1. Transport mechanism (WebSockets, SSE, polling?)
2. Current infrastructure capabilities
3. Scalability requirements
4. Client-side integration points

Let me research these first, then I'll present options and create the detailed plan. [Uses research command or explores]

[After research, presents 2-3 options with tradeoffs, gets alignment, then creates detailed plan]
```


---

### Implement Plan — Execute implementation plans phase by phase

> Skill name: `implement-plan`

# Implement Plan

Implement an approved plan following Test-Driven Development methodology.

## Getting Started

When given a plan path:
1. Read the plan completely (no limit/offset)
2. Check for existing checkmarks (✓ or [x]) indicating completed work
3. Read related specs/documentation referenced in the plan
4. Create a todo list to track progress through phases
5. Start implementing from the first unchecked phase

If no plan path provided, ask the user which plan to implement or list available plans.

## Implementation Philosophy

Follow the **Red, Green, Refactor** cycle:

1. **Red**: Write a failing test for the desired behavior
2. **Green**: Write minimal code to make the test pass
3. **Refactor**: Clean up code while keeping tests green

**Never skip the Red phase** - watching tests fail confirms they actually test something.

## Workflow

### For Each Phase:

#### Step 1: Read Phase Requirements

1. Read the phase section completely
2. Understand files to change and what changes are needed
3. Note the success criteria (automated and manual)
4. Check for any dependencies or prerequisites

#### Step 2: Write Tests First (TDD - RED)

1. Write test(s) that describe the desired behavior
2. Make tests as specific as possible
3. Run the tests - **confirm they fail** (and fail for the right reason)
4. If test doesn't fail, the test is wrong or code already works

```typescript
// Example: Write failing test first
describe('validateToken', () => {
  it('should accept valid JWT tokens', async () => {
    const token = 'valid.jwt.token'
    const result = await validateToken(token)
    expect(result.valid).toBe(true)
  })
})

// Run test: npm test
// ❌ FAILED: validateToken is not defined
// Good - fails for the right reason
```

#### Step 3: Implement Minimal Code (GREEN)

1. Write just enough code to make the test pass
2. Don't add features not tested yet
3. Resist the urge to "make it perfect" now
4. Run tests - **confirm they pass**

```typescript
// Minimal implementation to pass test
export async function validateToken(token: string) {
  const decoded = jwt.verify(token, SECRET)
  return { valid: true, userId: decoded.sub }
}

// Run test: npm test
// ✓ PASSED
```

#### Step 4: Refactor (if needed)

1. Clean up the code while tests stay green
2. Extract functions, improve names, remove duplication
3. Run tests after each refactor - **keep them green**
4. Stop when code is clean enough

```typescript
// Refactored with better error handling
export async function validateToken(token: string): Promise<TokenResult> {
  try {
    const decoded = jwt.verify(token, getSecret()) as JWTPayload
    return {
      valid: true,
      userId: decoded.sub
    }
  } catch (error) {
    return {
      valid: false,
      userId: null,
      error: error.message
    }
  }
}

// Run test: npm test
// ✓ Still passing after refactor
```

#### Step 5: Run Success Criteria Checks

**Automated verification:**
```bash
# Run all tests (not just the new ones)
npm test

# Type checking (if applicable)
npm run type-check  # or tsc --noEmit

# Linting (if applicable)
npm run lint

# Build (if applicable)
npm run build
```

**Manual verification:**
- Follow manual verification steps from the plan
- Actually perform the verification, don't skip it
- Note any issues or unexpected behaviors

#### Step 6: Mark Phase Complete

1. Check off completed items in the plan file
2. Update the plan with any learnings or deviations
3. Commit the changes for this phase (if appropriate)

#### Step 7: Inform User

```
Phase [N] Complete - Ready for Verification

Automated verification:
- [x] All tests pass (15 tests, 3 new)
- [x] Type checking passes
- [x] Build succeeds

Manual verification needed:
- [ ] [Manual step 1 from plan]
- [ ] [Manual step 2 from plan]

Changes made:
- src/auth/validate.ts:25-45 - Added validateToken function
- tests/auth/validate.test.ts:12-28 - Added 3 tests for token validation

Let me know when verified so I can proceed to Phase [N+1].
```

**Wait for user confirmation before proceeding to next phase.**

### Moving Between Phases

- Complete one phase before starting the next
- Don't work on multiple phases in parallel
- Each phase should leave the codebase in a working state
- If a phase is blocked, inform the user immediately

## When Things Don't Match Reality

If the plan doesn't match what you find:

```
Issue in Phase [N]:

Expected (from plan): [What the plan says]
Found (in codebase): [Actual situation]
Why this matters: [Impact explanation]

Options:
1. Adapt implementation to current reality
2. Update the plan to reflect new understanding
3. Ask user for guidance

How should I proceed?
```

**Important:** Don't blindly follow an outdated or incorrect plan. Reality wins.

## Resuming Work

If the plan has checkmarks indicating completed work:

1. **Trust completed work** - assume it's done correctly
2. **Start from first unchecked item** - don't redo completed work
3. **Verify previous work ONLY if**:
   - Something seems obviously broken
   - Tests are failing
   - Current phase depends on previous phase and seems incompatible
4. **Continue with Red-Green-Refactor** cycle from current phase

## Key Reminders

1. **Tests first, always** - Write test before implementation (TDD)
2. **Watch it fail** - Confirm test fails before implementing
3. **Minimal code** - Write just enough to pass the test
4. **Keep tests green** - All tests should pass after each change
5. **Refactor safely** - Only refactor when tests are green
6. **One phase at a time** - Complete and verify before moving on
7. **Mark progress** - Check off items as you complete them
8. **Verify thoroughly** - Actually run the verification steps

## Handling Common Situations

### Tests are already passing (someone implemented it):
```
Phase [N]: The tests I was about to write already pass. It appears this work was already completed.

Verification:
- [x] Tests exist and pass
- [x] Implementation matches plan requirements

Marking phase complete and moving to next phase.
```

### Can't make tests pass:
```
Phase [N]: Issue encountered

I wrote tests for [feature] but after [X] attempts, can't make them pass due to [specific reason].

Options:
1. Revise the approach (suggest alternative)
2. Update the plan (if requirements changed)
3. Need more research/context

How should we proceed?
```

### Found a better approach mid-implementation:
```
Phase [N]: Alternative approach discovered

While implementing [feature], I discovered [better pattern/approach].

Current plan: [Approach from plan]
Alternative: [New approach]
Tradeoffs: [Pros/cons]

Should I:
1. Continue with plan as written
2. Update plan and use new approach
3. Discuss further
```

### External dependency is broken/unavailable:
```
Phase [N]: Blocked by external dependency

Cannot proceed because [dependency] is [unavailable/broken/different than expected].

Impact: [What this blocks]
Workaround options: [If any]

Need guidance on how to proceed.
```

## Working with Issue Trackers

If using an issue tracker (GitHub Issues, Jira, etc.):

**Before starting:**
```bash
# Note the issue ID in commits
# Reference the plan in issue comments
```

**After completing a phase:**
```bash
# Update issue with progress
# Link commits to issue
# Add "Completed Phase N" comment
```

**After completing all phases:**
```bash
# Close or mark issue as ready for review
# Link to relevant commits/PRs
```

## Integration with Other Workflows

**After implementation:**
- Use `prompt-workflow-deliberate-commits.md` to commit changes thoughtfully
- Use `prompt-task-describe-pr.md` to create comprehensive PR descriptions
- Use `prompt-task-iterative-code-review.md` to self-review before committing

**If need to pause:**
- Use `prompt-workflow-create-handoff.md` to document progress
- Mark current phase status in todo list
- Note what's complete vs in-progress


---

### Iterate on Plan — Refine and improve existing plans based on feedback

> Skill name: `iterate-plan`

# Iterate Implementation Plan

Update an existing implementation plan based on feedback, grounded in codebase reality.

## When Invoked

**Three scenarios:**

1. **No plan file provided**: Ask for the plan path (list available plans in `plans/`)
2. **Plan file provided but NO feedback**: Ask what changes to make
3. **Both provided**: Proceed directly with updates

## Process

### Step 1: Understand Current Plan

1. **Read the existing plan file completely** (no limit/offset)
2. Understand the overall structure and approach
3. Note the phases, success criteria, and implementation decisions
4. Check for existing checkmarks (work already completed)
5. Identify what worked and what needs changing

### Step 2: Understand Requested Changes

**Listen carefully to what the user wants:**
- Are they adding new requirements?
- Changing the approach?
- Adding/removing phases?
- Adjusting scope?
- Fixing errors or omissions?

**Ask clarifying questions if unclear:**
- Use AskUserQuestion tool for ambiguous requests
- Confirm understanding before making changes
- Get specific about what success looks like

### Step 3: Research If Needed

**Only if changes require new technical understanding:**

1. Create a todo list for research tasks
2. Search for relevant patterns in the codebase
3. Read files that will be affected by changes
4. Check for existing documentation or specs
5. Validate feasibility of requested changes

**Use parallel research when possible** - run multiple searches/reads simultaneously.

**Skip research if:**
- Changes are straightforward (adding success criteria, clarifying wording)
- You already understand the technical context
- Changes are scope/organizational, not technical

### Step 4: Confirm Understanding

**Before making changes, confirm with the user:**

```
Based on your feedback, I understand you want to:
- [Change 1 with specific detail]
- [Change 2 with specific detail]

[If research was done:]
My research found:
- [Relevant code pattern or constraint]
- [Relevant existing implementation]

I plan to update the plan by:
1. [Specific modification to plan section X]
2. [Specific modification to plan section Y]

Does this align with your intent?
```

**Wait for confirmation before proceeding.**

### Step 5: Update the Plan

1. **Make focused, precise edits** to the existing plan
2. **Maintain existing structure** unless explicitly changing it
3. **Update success criteria** if scope changed
4. **Add new phases** following existing pattern
5. **Preserve completed work** - don't remove checkmarks or completed phases

**Ensure consistency:**
- If adding a phase, match the format of existing phases
- If modifying scope, update "Out of Scope" section
- If changing approach, update affected phases and success criteria
- Maintain automated vs manual success criteria distinction
- Update "Related" section if new specs/research referenced

**Use Edit tool for surgical changes:**
- Change specific sections, don't rewrite whole file
- Preserve good content
- Keep version history implicit (plan files don't need changelog)

### Step 6: Present Changes

```
I've updated the plan at `plans/[filename].md`

**Changes made:**
1. [Specific change 1 - section affected]
2. [Specific change 2 - section affected]
3. [Specific change 3 - section affected]

**Why these changes:**
[Brief rationale tying back to user's feedback]

**Impact:**
- [How this affects implementation effort, time, or approach]
- [Any new risks or dependencies]

Would you like any further adjustments?
```

### Step 7: Iterate If Needed

If user has more feedback:
- Repeat from Step 2
- Continue until plan is approved
- Track iterations with todo list if multiple rounds

## Guidelines

1. **Be Skeptical**: Question vague feedback, verify technical feasibility
2. **Be Surgical**: Make precise edits, preserve good content
3. **Be Thorough**: Read entire plan, understand context before changing
4. **Be Interactive**: Confirm understanding before making changes
5. **No Open Questions**: Ask immediately if changes raise questions
6. **Respect Completed Work**: Don't undo or modify completed phases without good reason
7. **Maintain Quality**: Updated plan should still be specific, actionable, and complete

## Common Iteration Scenarios

### Adding a New Phase

**User feedback:** "We also need to add API caching"

**Process:**
1. Understand where in sequence this phase belongs
2. Research existing caching patterns in codebase
3. Draft new phase following existing format
4. Update dependencies between phases if needed
5. Add to success criteria and testing strategy

### Changing Approach

**User feedback:** "Let's use Redis instead of in-memory caching"

**Process:**
1. Research Redis usage patterns in codebase
2. Identify all phases affected by this change
3. Update implementation approach in affected phases
4. Update success criteria (Redis-specific checks)
5. Update risks & mitigations section

### Adding Details

**User feedback:** "The authentication phase is too vague"

**Process:**
1. Identify what's unclear or missing
2. Research authentication implementation patterns
3. Add specific file paths and changes
4. Add detailed test requirements
5. Make success criteria more specific

### Removing Scope

**User feedback:** "Let's skip the admin UI for now"

**Process:**
1. Identify all phases related to admin UI
2. Move removed work to "Out of Scope" section
3. Remove dependencies on removed phases
4. Verify remaining phases still make sense
5. Update overall timeline/effort estimate

### Splitting a Phase

**User feedback:** "Phase 3 is too large, can we break it up?"

**Process:**
1. Identify logical split points in the phase
2. Create Phase 3a and 3b (or 3 and 4)
3. Divide success criteria appropriately
4. Add dependencies if one must come before the other
5. Renumber subsequent phases

### Correcting Errors

**User feedback:** "That approach won't work with our auth system"

**Process:**
1. Understand the constraint or conflict
2. Research the correct approach
3. Update affected phases with correct approach
4. Verify no other phases have same error
5. Update risks section if this revealed gaps

## Handling Difficult Iterations

### Plan is Fundamentally Wrong

If the plan needs >50% rewrite:
```
After reviewing your feedback and the codebase, I believe the current plan needs substantial restructuring rather than iteration.

Issues:
- [Fundamental issue 1]
- [Fundamental issue 2]

Recommendation: Create a new plan incorporating:
- [What to preserve]
- [What to change]

Would you like me to create a new plan, or should I attempt to salvage this one?
```

### Feedback Conflicts with Plan Structure

```
Your requested change [X] conflicts with existing Phase [N] which does [Y].

Options:
1. Modify Phase [N] to accommodate new change (impacts: ...)
2. Add new phase before/after [N] (impacts: ...)
3. Replace Phase [N] entirely (impacts: ...)

Which approach do you prefer?
```

### Feedback is Technically Infeasible

```
After researching, I found that [requested change] is not feasible because [technical reason].

Evidence:
- [File/code showing constraint]
- [Documentation or pattern showing limitation]

Alternative approaches:
1. [Alternative 1 - achieves similar goal]
2. [Alternative 2 - different tradeoff]

Which direction should we take?
```


---

### Rule of 5 Code Review (Multi-Agent) — High-stakes code review with parallel agent waves

> Skill name: `rule-of-5`

You are a master orchestrator of AI agents. Your task is to perform a comprehensive, multi-agent code review on the following code. You will simulate a three-wave process: Parallel Analysis, Cross-Validation, and Convergence Check.

**Code to Review:**
```
[PASTE YOUR CODE HERE]
```

**Your Instructions:**

**Wave 1: Parallel Independent Analysis**
Simulate five specialist agents running in parallel. Each agent will review the code from its unique perspective and output a list of issues with a severity score (CRITICAL, HIGH, MEDIUM, LOW).

1.  **Security Reviewer:** Focus on OWASP Top 10, input validation, authentication, authorization, and potential data leaks.
2.  **Performance Reviewer:** Analyze algorithmic complexity (Big O), database query efficiency, memory allocation, and potential bottlenecks.
3.  **Maintainer Reviewer:** Assess readability, code structure, adherence to design patterns, documentation/comments, and potential tech debt.
4.  **Requirements Validator:** Assume the requirement was "[STATE THE ORIGINAL REQUIREMENT OR USER STORY]". Check for requirement coverage, correctness, and missed edge cases.
5.  **Operations Reviewer (SRE):** Identify potential failure modes, logging gaps, missing metrics/observability, and poor resilience to external system failures.

**Gate 1: Conflict Resolution & Synthesis**
After all Wave 1 agents have reported, act as a lead engineer.
1.  Consolidate all findings into a single, deduplicated list.
2.  Resolve severity conflicts. A CRITICAL security issue outranks all other issues. An issue flagged by 3+ agents should be elevated in severity.
3.  Produce a prioritized list of findings from Wave 1.

**Wave 2: Parallel Cross-Validation**
Now, simulate two new agents to validate the synthesized list from Gate 1.

1.  **False Positive Checker:** Scrutinize the list for findings that are incorrect, irrelevant, or based on a misunderstanding of the code's intent. Mark them as `FALSE_POSITIVE`.
2.  **Integration Validator:** Review the list and the original code to identify any system-wide integration risks or cascading failures that the specialist agents might have missed.

**Gate 2: Final Synthesis**
Incorporate the results from Wave 2.
1.  Remove all issues marked `FALSE_POSITIVE`.
2.  Add any new integration risks.
3.  Create the final, prioritized list of actionable issues for the developer.

**Wave 3: Convergence Check**
Finally, assess the process. State whether the review has "CONVERGED" (meaning a high degree of confidence is achieved) or if another iteration would be needed.


---

### Create Issues from Plan — Generate trackable issues from implementation plans

> Skill name: `create-issues`

# Iterative Issue Creation from Plan

You will act as a project manager. Your task is to take the provided plan and create a set of issues in the specified issue tracking system. You will generate the precise, runnable commands to do so.

## Setup

### Input Plan

The plan to be implemented will be provided here. Your task is to parse it and create issues accordingly.

**Example Plan:**
```markdown
# Plan for New Authentication Feature

## Phase 1: Database Schema
- Add `password_hash` and `last_login` to the `users` table.
- File: `db/migrations/001_add_auth_fields.sql`

## Phase 2: Create Login Endpoint
- Create a new endpoint `POST /login`.
- It should take `email` and `password`.
- It should return a JWT.
- File: `src/auth/routes.ts`

## Phase 3: Protect Routes
- Create middleware that checks for a valid JWT.
- Apply it to the `/api/v1/profile` endpoint.
- File: `src/auth/middleware.ts`
```

## Process

For each phase or logical unit of work in the plan, create a corresponding issue. After creating all issues, define their dependencies.

### Issue Template

Each issue you create MUST use the following template for its title and description.

**Title:** A short, clear, action-oriented title (e.g., "Create Login Endpoint").

```
**Context:** [Brief explanation of what this issue is about, referencing the plan]
Ref: [Link to plan document and section]

**Files:**
- [List of files to be modified]

**Acceptance Criteria:**
- [ ] A checklist of what "done" means for this issue.

---
**CRITICAL: Follow Test Driven Development and Tidy First workflows.**
- Write tests *before* writing implementation code.
- Clean up related code *before* adding new functionality.
```

### Creating Issues and Dependencies

Generate the full, runnable commands to create the issues and then wire up their dependencies.

#### Strategy for Robust Execution

To ensure that dependencies are wired correctly, you MUST follow this three-step process:

1.  **Create Issues:** Run the creation command for each issue.
2.  **Capture IDs:** From the output of each command, capture the newly created issue ID or number and store it in a shell variable (e.g., `phase_1_issue_id=$(...)`). Most modern CLI tools provide a way to get machine-readable output (e.g., a `--porcelain` flag or simply the raw ID as the last line of output).
3.  **Connect Dependencies:** Use the variables from the previous step to run the dependency commands, ensuring you are linking the correct issues.

This prevents errors that can arise from assuming sequential or predictable issue IDs.

**Example for Beads:**
```bash
# Create issues for each phase, capturing the new issue ID from stdout
issue_1_id=$(bd create --title="DB Schema: Add auth fields to users table" --description="""
**Context:** As per the auth feature plan, we need to update the users table to support authentication.
Ref: plans/auth-feature.md#phase-1

**Files:**
- `db/migrations/001_add_auth_fields.sql`

**Acceptance Criteria:**
- [ ] Migration is created and applied.
- [ ] `users` table has `password_hash` and `last_login` fields.

---
**CRITICAL: Follow Test Driven Development and Tidy First workflows.**
- Write tests *before* writing implementation code.
- Clean up related code *before* adding new functionality.
""")

issue_2_id=$(bd create --title="API: Create Login Endpoint" --description="""
**Context:** Create the `POST /login` endpoint to authenticate users and issue JWTs.
Ref: plans/auth-feature.md#phase-2

**Files:**
- `src/auth/routes.ts`

**Acceptance Criteria:**
- [ ] Endpoint `POST /login` exists.
- [ ] It returns a JWT on successful login.
- [ ] It returns an error on failed login.

---
**CRITICAL: Follow Test Driven Development and Tidy First workflows.**
- Write tests *before* writing implementation code.
- Clean up related code *before* adding new functionality.
""")

# (Assume issue for Phase 3 is also created and its ID is in $issue_3_id)

# Set dependencies using the captured IDs
bd dep add "$issue_2_id" "$issue_1_id"  # login endpoint depends on db schema
# bd dep add "$issue_3_id" "$issue_2_id" # middleware depends on login endpoint
```

**Example for GitHub Issues:**
```bash
# Create issues, capturing the new issue URL from stdout
issue_1_url=$(gh issue create --title "DB Schema: Add auth fields to users table" --body "...") # (full body as above)
issue_2_url=$(gh issue create --title "API: Create Login Endpoint" --body "...")
# ...

# Extract the issue numbers from the URLs
issue_1_number=$(echo "$issue_1_url" | sed 's/.*\\///')
issue_2_number=$(echo "$issue_2_url" | sed 's/.*\\///')

# Note dependencies in the body. Since gh CLI has no formal dep command,
# we add a reference to the blocking issue in the body of the dependent issue.
gh issue edit "$issue_2_number" --body "$(gh issue view "$issue_2_number" --json body -q .body)

Blocked by #$issue_1_number"
```

## Final Report

After generating all commands, provide a final summary report in the following format.

```
## Issue Creation Summary

**System:** [Beads/GitHub/Linear/Jira]
**Plan:** [path/to/plan.md]

### Summary

- Total Issues Created: [count]
- Dependencies Defined: [count]

### Verdict

[ISSUES_CREATED | FAILED_TO_CREATE]

**Rationale:** [1-2 sentences explaining the result, e.g., "Successfully created all issues and dependencies from the plan."]
```


---

### Distill Prompt — Create lean, token-efficient versions of prompts

> Skill name: `distill-prompt`

Analyze the provided DEVELOPER-FACING PROMPT. Your task is to distill it into a concise, token-efficient, LLM-FACING PROMPT.

The distilled prompt must retain only the essential instructions, rules, and structured commands required for the LLM to perform its task.

You MUST REMOVE:
1.  All front-matter and metadata (e.g., title, tags, status, version, related, source).
2.  All explanatory sections intended for humans (e.g., "When to Use," "Notes," "Example," "References," "Philosophy").
3.  Descriptive introductions, justifications, and conversational text.
4.  Verbose examples. Summarize them only if they are essential for defining a format.

The final output should be a clean, direct set of instructions for the LLM, with no additional commentary from you.

DEVELOPER-FACING PROMPT:
---
[Paste the verbose prompt content here]
---


---

### Verify Distilled Prompt — Validate distilled prompts preserve essential instructions

> Skill name: `verify-prompt`

You are a meticulous QA assistant. Your task is to compare two versions of a prompt: the `ORIGINAL_PROMPT` (verbose, for developers) and the `DISTILLED_PROMPT` (concise, for LLMs).

Your goal is to verify that the `DISTILLED_PROMPT` is a faithful, lossless distillation of the `ORIGINAL_PROMPT`.

**Analysis Criteria:**
1.  **Completeness**: Does the `DISTILLED_PROMPT` include ALL essential executable instructions, steps, rules, and constraints from the `ORIGINAL_PROMPT`?
2.  **Accuracy**: Does the `DISTILLED_PROMPT` correctly represent the core logic and intent of the original? There should be no changes in meaning.
3.  **Conciseness**: The `DISTILLED_PROMPT` should have successfully removed non-essential content like human-facing explanations, examples, metadata, and conversational filler.

**Your Task:**
1.  Carefully analyze both prompts provided below.
2.  Compare them against the criteria above.
3.  If the `DISTILLED_PROMPT` is a perfect, lossless distillation, respond with only:
    `OK`
4.  If there are any discrepancies (e.g., a missing step, an altered instruction), provide a concise report detailing ONLY the specific, essential content that is missing or altered in the `DISTILLED_PROMPT`. Do not comment on what was correctly removed.

---
**ORIGINAL_PROMPT:**
```
[Paste the original verbose prompt content here]
```
---
**DISTILLED_PROMPT:**
```
[Paste the distilled concise prompt content here]
```
---


---

### Research Codebase — Structured investigation of unfamiliar codebases

> Skill name: `research-codebase`

# Research Codebase

Document and explain the codebase as it exists today.

## CRITICAL RULES

**You are a documentarian, not an evaluator:**

1. ✅ **DO:** Describe what exists, where it exists, and how it works
2. ✅ **DO:** Explain patterns, conventions, and architecture
3. ✅ **DO:** Provide file:line references for everything
4. ✅ **DO:** Show relationships between components
5. ❌ **DO NOT:** Suggest improvements or changes
6. ❌ **DO NOT:** Critique the implementation
7. ❌ **DO NOT:** Recommend refactoring
8. ❌ **DO NOT:** Say things like "could be improved" or "should use"

## Process

### Step 1: Understand the Research Question

[User will provide a question like:]
- "How does authentication work?"
- "Where are errors handled?"
- "What's the data flow for user registration?"
- "Document the API layer architecture"

**Clarify if needed:**
- What specific aspect to focus on?
- What level of detail is needed?
- Any specific files already identified?

### Step 2: Decompose the Question

Break down the research into searchable components:

```
Research question: "How does authentication work?"

Components to investigate:
1. Where authentication logic lives
2. What authentication methods exist
3. How authentication state is managed
4. Where authentication is validated
5. How errors are handled
6. What the authentication flow looks like
```

### Step 3: Research with Parallel Searches

Use search tools efficiently:

```bash
# Find auth-related files
find . -name "*auth*" -type f

# Search for authentication patterns
grep -r "authenticate" --include="*.ts" --include="*.js"
grep -r "login" --include="*.ts" --include="*.js"

# Look for middleware or hooks
grep -r "middleware" --include="*.ts"
grep -r "useAuth" --include="*.tsx"

# Find configuration
grep -r "auth" config/ .env.example
```

### Step 4: Read Identified Files

**Read completely, don't skim:**
- Read files from top to bottom
- Note imports and dependencies
- Track how components connect

### Step 5: Document Findings

**Template for research output:**

```markdown
# Research: [Topic]

**Date:** [ISO date]
**Question:** [Original research question]

## Summary

[2-3 paragraph high-level overview of findings]

## Architecture Overview

[Describe the overall architecture for this component/feature]

```
[Optional ASCII diagram showing relationships]
```

## Key Components

### Component 1: [Name]

**Location:** `path/to/file.ext:123-456`
**Purpose:** [What it does]
**Used by:** [What depends on this]
**Depends on:** [What this depends on]

**How it works:**
[Step-by-step explanation of the implementation]

**Key methods/functions:**
- `functionName()` (line 123): [What it does]
- `anotherFunction()` (line 145): [What it does]

### Component 2: [Name]
[Same structure]

## Data Flow

[Describe how data flows through the system for this feature]

1. User action triggers X
2. X calls Y with data
3. Y validates and transforms data
4. Y passes to Z
5. Z persists/returns result

**File references:**
- Step 1: `src/components/Button.tsx:67`
- Step 2: `src/handlers/handler.ts:23`
- Step 3: `src/validators/validate.ts:89`
- etc.

## Patterns and Conventions

**Pattern 1:** [Describe pattern found]
- Used in: [file:line, file:line]
- Purpose: [Why this pattern]

**Pattern 2:** [Another pattern]
- Used in: [file:line]

## Configuration

**Environment variables:**
- `AUTH_SECRET` - Used in `src/auth/jwt.ts:12`
- `AUTH_EXPIRY` - Used in `src/auth/jwt.ts:34`

**Config files:**
- `config/auth.json` - Contains [what]

## Error Handling

[How errors are handled in this area]

- Error types: [List error types]
- Error handlers: `src/errors/AuthError.ts:23`
- User-facing errors: [How shown to users]

## Testing

**Test files:**
- `tests/auth.test.ts` - Tests [what]
- `tests/integration/auth.integration.test.ts` - Tests [what]

**Coverage:** [If determinable]
**Test patterns:** [How tests are structured]

## Dependencies

**External libraries:**
- `jsonwebtoken` - Used for JWT creation/validation
- `bcrypt` - Used for password hashing

**Internal dependencies:**
- `src/db/users.ts` - User data access
- `src/utils/validation.ts` - Input validation

## Entry Points

**Where this feature is invoked:**
1. `src/routes/auth.ts:45` - Login endpoint
2. `src/middleware/authCheck.ts:12` - Auth middleware
3. `src/components/LoginForm.tsx:89` - Login UI

## Related Code

**Related features:**
- Authorization (see `src/authz/`)
- User management (see `src/users/`)
- Session management (see `src/sessions/`)

## Related Documentation

**Docs:**
- `docs/authentication.md` (if exists)
- `README.md` sections on auth

**Code Comments:**
[Notable code comments that explain design decisions]

## Open Questions

[Things that are unclear or need further investigation]
- [ ] How are refresh tokens handled?
- [ ] What happens on token expiry during request?
```

## Guidelines

1. **Be precise** - Include file:line for every claim
2. **Be objective** - Describe, don't judge
3. **Be thorough** - Cover all aspects of the question
4. **Show relationships** - How components connect
5. **Capture patterns** - Note conventions used throughout
6. **Include config** - Environment variables, config files
7. **Track tests** - Document existing test coverage


---

### Create Handoff Document — Generate context documents for session continuity

> Skill name: `create-handoff`

# Create Handoff Document

Create a concise handoff document to transfer context to another agent session.
Compress and summarize the context without losing key details.

## Process

### Step 1: Gather Metadata

```bash
# Get current state
git branch --show-current
git rev-parse --short HEAD
date -Iseconds
pwd
```

### Step 2: Determine Filepath

Create file at `handoffs/YYYY-MM-DD_HH-MM-SS_description.md`

**Naming patterns:**
- With issue tracking: `handoffs/2026-01-12_14-30-00_issue-123_add-oauth.md`
- Without issues: `handoffs/2026-01-12_14-30-00_refactor-auth-system.md`

### Step 3: Write Handoff Document

**Template:**

```markdown
---
date: [ISO timestamp with timezone]
git_commit: [short hash]
branch: [branch name]
directory: [working directory]
issue: [issue-123 if applicable]
status: handoff
---

# Handoff: [brief description]

## Context

[1-2 paragraph overview of what we're working on and why]

## Current Status

### Completed
- [x] [Task 1 with file:line references]
- [x] [Task 2 with file:line references]

### In Progress
- [ ] [Task being worked on with current state]

### Planned
- [ ] [Next task]
- [ ] [Future task]

## Critical Files

> These are the MOST IMPORTANT files to understand for continuation

1. `path/to/critical/file.ext:123-156` - Core implementation of X
2. `path/to/config.ext:45` - Configuration for Y
3. `path/to/test.ext` - Existing tests that constrain changes

## Recent Changes

> Files modified in this session

- `src/auth/oauth.ts:34-89` - Added OAuth flow orchestration
- `src/auth/providers.ts:1-134` - Created provider abstraction (new file)
- `src/components/LoginForm.tsx:67-89` - Integrated OAuth UI
- `tests/oauth.test.ts:1-67` - Unit tests for OAuth (new file)

## Key Learnings

> Important discoveries that affect future work

1. **OAuth state must be stored in sessionStorage**
   - LocalStorage persists across tabs causing state confusion
   - See `src/auth/oauth.ts:45` for implementation

2. **Provider interface needs async initialization**
   - Some providers require config fetching before use
   - Current implementation in `src/auth/providers.ts:23`

3. **Existing auth system uses context pattern**
   - Must integrate OAuth without breaking existing email/password
   - See `src/contexts/AuthContext.tsx` for pattern

## Open Questions

> Unresolved decisions or uncertainties

- [ ] Should OAuth tokens be stored in httpOnly cookies or localStorage?
- [ ] Need to verify PKCE flow works with all providers
- [ ] How to handle provider-specific scopes?

## Next Steps

> Prioritized actions for next session

1. **Test OAuth flow end-to-end** [Priority: HIGH]
   - Test with real provider credentials
   - Verify token refresh works
   - Check error handling

2. **Add provider configuration UI** [Priority: MEDIUM]
   - Allow admin to enable/disable providers
   - Configure client IDs per environment

3. **Document OAuth setup** [Priority: MEDIUM]
   - Update README with provider setup instructions
   - Add environment variable documentation

## Artifacts

> Complete list of files created/modified

**New files:**
- `src/auth/oauth.ts`
- `src/auth/providers.ts`
- `tests/oauth.test.ts`

**Modified files:**
- `src/components/LoginForm.tsx`
- `src/types/auth.ts`

**Not committed:** [if applicable]
- `config/development.env` (local credentials)

## Related Links

> Links to relevant docs, discussions, or research

- [OAuth 2.0 spec](https://oauth.net/2/)
- Slack discussion: #auth-redesign (2026-01-10)
- Design doc: `docs/oauth-integration.md`

## Additional Context

> Any other useful context

- Testing locally requires registered OAuth apps for each provider
- Google OAuth has strict redirect URI validation
- GitHub provider works but needs organization scope review
```

### Step 4: Commit the Handoff

```bash
git add handoffs/YYYY-MM-DD_HH-MM-SS_description.md
git commit -m "docs(handoff): add handoff for [brief description]"
```

### Step 5: Inform User

```
Handoff created at: handoffs/2026-01-12_14-30-00_oauth-integration.md

To resume in a new session:
1. Start fresh AI session
2. Provide the prompt: "Resume work from handoffs/2026-01-12_14-30-00_oauth-integration.md"
3. Or use: /resume_handoff handoffs/2026-01-12_14-30-00_oauth-integration.md

The handoff captures:
- Current task status
- Key learnings and decisions
- Files to read first
- Prioritized next steps
```

## Guidelines

1. **Be specific, not vague** - Include file:line references for everything
2. **Capture the "why"** - Future sessions need to understand decisions
3. **Prioritize learnings** - Mistakes and discoveries are most valuable
4. **Reference, don't duplicate** - Link to files rather than copy code
5. **Update issue tracking** - If using issues, link the handoff


---

### Resume from Handoff — Continue work from a previous session's handoff document

> Skill name: `resume-handoff`

# Resume from Handoff

Resume work from a handoff document through analysis and verification.

## Step 1: Read Handoff Completely

**If given a handoff path:**
```bash
# Read the handoff file
cat handoffs/2026-01-12_14-30-00_oauth-integration.md
```

**If given an issue ID:**
```bash
# Find handoffs for this issue
ls handoffs/*issue-123* | sort -r | head -1

# Or search in handoff content
grep -l "issue: issue-123" handoffs/*.md | sort -r | head -1
```

**If no parameter provided:**
```bash
# List recent handoffs
ls -lt handoffs/ | head -10

# Ask user which to resume
```

## Step 2: Extract Key Information

From the handoff, identify:

**Task Status:**
- What was completed?
- What's in progress?
- What's planned?

**Critical Files:**
- Which files are most important?
- What are the line ranges mentioned?

**Key Learnings:**
- What discoveries affect our work?
- What mistakes should we avoid?

**Open Questions:**
- What needs decisions?
- What was uncertain?

**Next Steps:**
- What's the prioritized todo list?

## Step 3: Verify Current State

```bash
# Check if anything changed since handoff
git log --oneline [handoff_commit]..HEAD

# Check current branch
git branch --show-current

# Check working directory status
git status

# Compare current state to handoff state
git diff [handoff_commit]
```

## Step 4: Read Referenced Files

Read the "Critical Files" section files:

```bash
# Read each critical file mentioned
cat src/auth/oauth.ts
cat src/auth/providers.ts
# ... etc
```

**Focus on:**
- Understanding current implementation
- Verifying learnings still apply
- Finding any conflicts with changes since handoff

## Step 5: Present Analysis

```
I've analyzed the handoff from [date]. Here's the current situation:

## Original Context
[Summary of what was being worked on]

## Task Status Review

**Completed (from handoff):**
- [x] Task 1 - VERIFIED: Still complete
- [x] Task 2 - VERIFIED: Still complete

**In Progress (from handoff):**
- [ ] Task 3 - STATUS: [describe current state]

**Planned:**
- [ ] Next task 1 [Priority from handoff]
- [ ] Next task 2

## Changes Since Handoff

**Commits since handoff:**
[List any commits between handoff and now]

**Impact:**
[How these changes affect our work]

## Key Learnings Still Applicable

1. [Learning 1] - Still valid because [reason]
2. [Learning 2] - Still valid, see [file:line]

## Questions Needing Resolution

From handoff:
- [ ] [Question 1] - [Current thinking or need decision]
- [ ] [Question 2] - [Can we resolve this now?]

## Recommended Next Action

Based on the handoff priorities and current state:

**Priority 1:** [Action from handoff]
- Reason: [Why this is still the priority]
- Files: [What needs to change]
- Approach: [How to do it]

Shall I proceed with [action]?
```

## Step 6: Get Confirmation and Begin

Wait for user confirmation, then:
- Create todo list from next steps
- Start with highest priority action
- Apply learnings from handoff
- Track progress as you go

## Scenarios

### Clean Continuation
All changes present, no conflicts, proceed normally.

### Diverged Codebase
```
Changes detected since handoff:

Commit a1b2c3d: "refactor: restructure auth module"
- Affects our OAuth implementation
- Provider files moved to src/auth/providers/ directory
- Need to update our understanding

I'll read the new structure before proceeding. Let me check:
- src/auth/providers/ directory contents
- How existing patterns changed
- If our learnings still apply

[After reading]

Updated understanding:
- Providers now in separate directory (not one file)
- Pattern still the same, just reorganized
- Our work can continue with file path updates

Shall I proceed with the original plan, adapting to new structure?
```

### Incomplete Work
```
The handoff shows Task 3 was "in progress". Let me verify current state:

[Reads relevant files]

Current state: Task 3 is partially done:
- OAuth flow implemented
- Provider selection NOT YET implemented
- Error states missing

Recommended approach:
1. Complete Task 3 first (finish what was started)
2. Then proceed to planned work

Shall I complete Task 3 before moving to new work?
```

### Stale Handoff
```
The handoff is from [3 weeks ago]. Significant changes detected:

Changes:
- 47 commits since handoff
- Auth system refactored
- New OAuth library integrated

This handoff may be too stale to resume directly.

Options:
1. Review changes and adapt the plan
2. Start fresh with current codebase state
3. Cherry-pick specific unfinished work

What would you like to do?
```

## Guidelines

1. **Always verify before acting** - Don't assume handoff matches reality
2. **Apply learnings** - Use documented patterns and avoid noted pitfalls
3. **Check open questions** - Some may be resolved or need decisions now
4. **Respect priorities** - Handoff author prioritized for a reason
5. **Adapt to changes** - If codebase changed, acknowledge and adapt
6. **Create new handoff** - When this session ends, update or create new one


---

### Design in Practice — Rich Hickey-inspired design methodology workflow

> Skill name: `design-practice`

Apply the 6-phase design framework to understand a problem before implementing a solution.

## Phases

Work through each phase sequentially. Do not skip phases. The goal is understanding, not artifacts.

### PHASE 1: DESCRIBE (Symptoms)

**Objective:** Capture the reality without imposing solutions.

1. **Gather signals:**
   - What symptoms are observed? (errors, complaints, metrics)
   - Where do they occur? (files, components, conditions)
   - When did they start? (commits, deployments, changes)
   - Who is affected? (users, systems, processes)

2. **Write a neutral description:**
   - Facts only, no speculation on causes
   - No mention of solutions
   - Observable behaviors, not interpretations

**Output format:**
```
## Description

### Observed Symptoms
- [Symptom 1]: [Where/When observed]
- [Symptom 2]: [Where/When observed]

### Signal Sources
- [Bug reports, logs, user complaints, metrics]

### Timeline
- [When symptoms first appeared, any patterns]
```

**Anti-patterns to avoid:**
- "The database is slow" (diagnosis, not description)
- "We need to add caching" (solution, not description)
- "Users are confused by the UI" (interpretation, not observation)

**Correct examples:**
- "Page load time exceeds 5s when user count > 100"
- "Error rate increased from 0.1% to 2.3% after deploy on Jan 15"
- "Users submit support tickets asking how to find the export button"

### PHASE 2: DIAGNOSE (Root Cause)

**Objective:** Identify the mechanism causing the symptoms.

1. **Generate multiple hypotheses:**
   - List at least 3 possible causes
   - "If I only have one hypothesis, I'm probably wrong"

2. **Test hypotheses systematically:**
   - Use logic to rule things out (negative progress)
   - Use evidence to support remaining hypotheses
   - Divide and conquer (git bisect, component isolation)

3. **Write the Problem Statement:**

**Problem Statement Template:**
```
## Problem Statement

**Current behavior:** [What happens now - factual]

**Mechanism:** [Root cause - how/why it happens]

**Evidence:**
- [Fact supporting this diagnosis]
- [Fact supporting this diagnosis]

**Ruled out:**
- [Hypothesis A]: [Why it's not this]
- [Hypothesis B]: [Why it's not this]
```

**Quality check:** The solution should feel obvious after writing the right problem statement. If it doesn't, the diagnosis is incomplete.

### PHASE 3: DELIMIT (Scope)

**Objective:** Define what's in and what's out.

1. **Set explicit boundaries:**
   - What subset of the problem will we solve?
   - What constraints do we accept?
   - What's explicitly NOT being addressed?

2. **Document non-goals:**
   - Future considerations
   - Related problems not in scope
   - Nice-to-haves deferred

**Output format:**
```
## Scope

### In Scope
- [What we will address]
- [Specific constraints we'll work within]

### Out of Scope (Non-Goals)
- [What we explicitly won't do]
- [Why it's deferred]

### Constraints
- [Technical limitations]
- [Time/resource constraints]
- [Compatibility requirements]
```

**Why this matters:** Prevents scope creep. Sets the "physics" of the project before considering solutions.

### PHASE 4: DIRECTION (Strategic Approach)

**Objective:** Select the best approach from viable alternatives.

1. **Generate multiple approaches:**
   - **Status Quo**: Always include "do nothing" as baseline
   - **Approach A**: [First viable approach]
   - **Approach B**: [Different viable approach]
   - **Approach C**: [If applicable]

2. **Build a Decision Matrix:**

**Decision Matrix Structure:**
```
## Decision Matrix

| Criterion | Status Quo | Approach A | Approach B |
|-----------|------------|------------|------------|
| [Criterion 1] | [Fact] | [Fact] | [Fact] |
| [Criterion 2] | [Fact] | [Fact] | [Fact] |
| [Criterion 3] | [Fact] | [Fact] | [Fact] |

### Criteria Definitions
- **[Criterion 1]**: [What this measures]
- **[Criterion 2]**: [What this measures]

### Assessment Key
- Green: Desirable
- Yellow: Acceptable with trade-offs
- Red: Problematic or blocking
```

**Rules for Decision Matrix:**
- Text is FACT (neutral, objective descriptions)
- Color/assessment is JUDGMENT (subjective evaluation)
- Status Quo is always the first column
- Each cell must be specific, not "good" or "bad"

3. **Select and justify:**
```
### Decision

**Selected approach:** [Approach name]

**Rationale:** [Why this approach best addresses the scoped problem]

**Trade-offs accepted:** [What we're giving up]
```

### PHASE 5: DESIGN (Tactical Plan)

**Objective:** Create detailed blueprint for implementation.

Only after Direction is selected:

1. **Define specifics:**
   - Data structures and schemas
   - API signatures and contracts
   - Component responsibilities
   - Error handling approach
   - Edge cases

2. **Write Implementation Plan:**

Use the standard implementation plan format with:
- Phases that can be independently verified
- TDD approach (tests before implementation)
- Specific file paths and changes
- Success criteria for each phase

**Hammock time:** Write the plan, then sleep on it. Read it the next day before proceeding.

### PHASE 6: DEVELOP (Execute)

**Objective:** Translate design into working code.

If Phases 1-5 were rigorous, this phase should feel mechanical:
- Follow the plan
- Write tests first
- Implement to pass tests
- Verify against success criteria

**If you're struggling in this phase:** Return to earlier phases. Struggling to code usually means the design is incomplete.

## Process Rules

1. **No phase skipping:** Each phase builds on the previous
2. **Artifacts are thinking tools:** Not bureaucracy, but aids to understanding
3. **Hammock time:** Sleep on ideas before committing to them
4. **Multiple hypotheses:** One idea is a trap; generate alternatives
5. **Incremental over iterative:** Understand → Design → Code → Value (not Code → Fail → Learn)

## When to Return to Earlier Phases

- **Can't write Problem Statement clearly** → Back to Describe (need more symptoms)
- **Solution doesn't feel obvious** → Back to Diagnose (incomplete root cause)
- **Scope keeps expanding** → Back to Delimit (boundaries not firm)
- **Can't choose between approaches** → Back to Direction (need more criteria or research)
- **Implementation keeps hitting surprises** → Back to Design (missing edge cases)


---

### Extract Prompt from Conversation — Turn successful interactions into reusable prompts

> Skill name: `extract-prompt`

# Extract Reusable Prompt from Conversation

Analyze this conversation and extract a reusable prompt that captures the successful pattern.

## Process

### Step 1: Analyze the Conversation

Review the entire conversation and identify:

**What was the goal?**
- What were we trying to accomplish?
- What problem were we solving?

**What made it successful?**
- What specific instructions led to good results?
- What constraints or guidelines were important?
- What structure or process did we follow?

**What was the key pattern?**
- Can this be generalized beyond this specific case?
- What made this approach effective?
- What would need to change for different contexts?

### Step 2: Extract the Pattern

Identify the core pattern:

**The problem it solves:**
[General class of problems this addresses]

**The approach:**
[The method or structure that worked]

**Critical elements:**
- [Key instruction 1 that made it work]
- [Key instruction 2]
- [Key constraint or guideline]

**Optional elements:**
- [Things that helped but aren't essential]

### Step 3: Generalize the Instructions

Convert the specific conversation into general instructions:

**From specific:**
"Read src/auth/oauth.ts and explain how it works"

**To general:**
"Read [FILE] and explain how it works"

**From specific:**
"Don't suggest improvements to the authentication system"

**To general:**
"Document what exists without suggesting improvements"

### Step 4: Structure the Prompt

Create a structured prompt document following the template:

```markdown
---
title: [Descriptive Title]
type: prompt
tags: [tag1, tag2, tag3]
tools: [applicable-tools]
status: draft
created: [YYYY-MM-DD]
version: 1.0.0
related: []
source: extracted-from-conversation
---

# [Title]

## Applicability

[When is this prompt appropriate? What problems does it solve?]

**Critical for:**
- [Use case 1]
- [Use case 2]

**Do NOT use for:**
- [Anti-pattern 1]
- [Anti-pattern 2]

## The Prompt

\```
[The actual prompt text, generalized and structured]

[Include key sections like:]

## Critical Rules

[Non-negotiable guidelines]

## Process

[Step-by-step workflow if applicable]

### Step 1: [Name]
[Instructions]

### Step 2: [Name]
[Instructions]

## Guidelines

[Best practices and recommendations]
\```

## Usage Scenario

**Context:**
[Describe a concrete scenario]

**Input:**
\```
[What you would actually say to the AI]
\```

**Expected Output:**
\```
[What the AI should produce]
\```

## Success Criteria

[What success looks like]
- [Expected outcome 1]
- [Expected outcome 2]

## Variations

[Different versions for different contexts]

## Related Links

[Links to sources or related information]

## Additional Context

[Caveats or tips]

## Changelog

- 1.0.0 ([YYYY-MM-DD]): Initial extraction from conversation
```

### Step 5: Provide Context from This Conversation

Include specific details:

**What we did:**
[Summary of this specific conversation]

**What worked well:**
[Specific things that led to success]

**What could be generalized:**
[Parts that apply to similar situations]

**Example from this conversation:**
[Use this conversation as the example in the prompt]

### Step 6: Determine Filename

Following naming conventions:

**For workflows (multi-step):**
`prompt-workflow-[descriptive-slug].md`

**For tasks (single focused task):**
`prompt-task-[descriptive-slug].md`

**For system prompts:**
`prompt-system-[descriptive-slug].md`

### Step 7: Classify and Tag

**Type:** prompt
**Status:** draft (needs testing)
**Tags:** [Extract 3-5 relevant tags]
**Tools:** [Which tools would this work with?]

### Step 8: Present Draft

```
I've extracted a reusable prompt from our conversation.

**Pattern identified:** [Name of pattern]

**Key insight:** [What made this work]

**Proposed filename:** content/prompt-[type]-[slug].md

**Draft prompt:**
[Show the structured prompt document]

This prompt could be useful for [use cases].

Shall I:
1. Save this prompt to the content/ directory
2. Make adjustments first
3. Test it in a new conversation
```

## Guidelines

1. **Generalize without losing specificity** - Keep concrete examples but make instructions general
2. **Capture the "why"** - Don't just transcribe, explain what made it work
3. **Include anti-patterns** - Document when NOT to use it
4. **Provide examples** - Use this conversation as a concrete example
5. **Start with "draft" status** - Needs testing before "tested" or "verified"
6. **Cross-reference** - Link to related prompts
7. **Iterate** - First version doesn't have to be perfect


---

### Pre-Mortem Planning — Anticipate failures before they happen

> Skill name: `pre-mortem`

Imagine it is [FUTURE DATE, e.g., six months from now]. The [PROJECT NAME] project has failed spectacularly. It was a complete disaster, resulting in [SPECIFIC NEGATIVE BUSINESS OUTCOME, e.g., 40% customer churn, a major security breach, a total budget overrun].

You are the lead investigator writing the internal autopsy report. Your job is to uncover the root causes of the failure.

Do not speculate on *if* it might fail. You must assume it *has* failed.

Your task:
1. Write a brief, 1-2 paragraph narrative describing how the failure unfolded.
2. Based on that narrative, identify the top 3-5 root causes of the failure. For each root cause, trace it back to a specific decision, assumption, or action made in the plan *today*.
3. Be specific and unflinching in your analysis. Your goal is to provide the team with the "prospective hindsight" needed to prevent this future from happening.


---

### Plan-Implement-Verify (TDD) — Test-driven development workflow

> Skill name: `tdd`

# Implement with TDD Workflow

Implement the requested feature following Test-Driven Development and a phased approach.

## Core Principle: Red, Green, Refactor

**Red:** Write a failing test that describes desired behavior
**Green:** Write minimal code to make the test pass
**Refactor:** Clean up code while keeping tests green

## Process

### Phase 0: Plan (If needed)

**For complex features, create a plan first:**

1. Read relevant code to understand current state
2. Identify what needs to change
3. Break work into logical phases
4. Define success criteria (automated and manual)
5. Get user approval of plan before implementing

**Plan structure:**
```markdown
# [Feature Name] Implementation Plan

## Current State
[What exists now]

## Desired End State
[What will exist, how to verify]

## Out of Scope
[What we're NOT doing]

## Phase 1: [Name]

### Changes Required
- File: `path/to/file.ext`
- Changes: [Description]
- Tests: [What tests to write]

### Success Criteria

#### Automated:
- [ ] New tests pass
- [ ] Existing tests still pass
- [ ] Type checking passes (if applicable)

#### Manual:
- [ ] [Specific manual verification]

## Phase 2: [Name]
[Continue...]
```

**Get plan approved before proceeding.**

### Phase 1: Implement First Component

**For each phase:**

#### Step 1: Write Failing Test

```typescript
// RED: Test describes what should happen
describe('UserAuthentication', () => {
  it('should validate JWT tokens', async () => {
    const token = 'valid.jwt.token'
    const result = await validateToken(token)
    expect(result).toEqual({ userId: '123', valid: true })
  })
})
```

Run test: **Confirm it fails** (and fails for the right reason)

#### Step 2: Implement Minimal Code

```typescript
// GREEN: Minimal implementation to pass test
async function validateToken(token: string) {
  // Simplest thing that could work
  const decoded = jwt.verify(token, SECRET)
  return {
    userId: decoded.sub,
    valid: true
  }
}
```

Run test: **Confirm it passes**

#### Step 3: Refactor If Needed

```typescript
// REFACTOR: Clean up while keeping tests green
async function validateToken(token: string): Promise<TokenResult> {
  try {
    const decoded = jwt.verify(token, getSecret()) as JWTPayload
    return {
      userId: decoded.sub,
      valid: true
    }
  } catch (error) {
    return { userId: null, valid: false, error: error.message }
  }
}
```

Run tests: **Confirm they still pass**

#### Step 4: Verify Phase Completion

**Automated verification:**
```bash
# Run all tests
npm test

# Run type checking (if applicable)
npm run type-check

# Run linting (if applicable)
npm run lint
```

**Manual verification:**
- [ ] [Specific manual tests from plan]

#### Step 5: Inform User

```
Phase 1 Complete - Ready for Verification

Automated verification:
- [x] Tests pass (12 new tests, all existing tests still passing)
- [x] Type checking passes
- [x] Linting passes

Manual verification needed:
- [ ] [Manual verification step 1]
- [ ] [Manual verification step 2]

Changes made:
- src/auth/validate.ts: Added validateToken function
- tests/auth/validate.test.ts: Added 12 tests covering valid/invalid tokens

Let me know when verified so I can proceed to Phase 2.
```

**Wait for user confirmation before proceeding.**

### Phase 2, 3, etc.: Repeat

Continue with each phase following the same Red-Green-Refactor cycle.

## Key Guidelines

1. **Tests first, always** - Write the test before the implementation
2. **Minimal implementation** - Write just enough code to pass the test
3. **One phase at a time** - Complete and verify before moving on
4. **Keep tests green** - Never commit with failing tests
5. **Refactor with green tests** - Only clean up when tests pass
6. **Verify at each phase** - Automated and manual checks
7. **Update plan** - Check off completed items as you go

## When Things Don't Match

If reality doesn't match the plan:

```
Issue in Phase [N]:

Expected: [What the plan says]
Found: [Actual situation]
Why this matters: [Explanation]

Options:
1. Adapt implementation to reality
2. Update plan to reflect new understanding
3. Discuss with user

How should I proceed?
```

**Don't blindly follow an outdated plan.**

## Resuming Work

If resuming from an existing plan:

1. Read the plan completely
2. Check for items already checked off
3. Start from first unchecked item
4. Verify previous work if something seems off
5. Continue with Red-Green-Refactor cycle


---

### Write Narrative Article — Create engaging technical articles with narrative structure

> Skill name: `narrative-article`

# Write a Narrative-Driven Article

We will collaborate to write a compelling article or blog post using the Three-Act narrative structure. We will work through four phases: Idea, Outline, Draft, and Review.

## Phase 1: The Idea (The Setup)

First, we must define the core of our story. Please answer these questions:

1.  **What is the main topic or subject?**
2.  **Who is the target audience?** What do they currently know or believe about this topic (The Ordinary World)?
3.  **What is the central question or problem you want to address?** This is the "Inciting Incident" that will hook the reader. What puzzle will this article solve?
4.  **What is the key takeaway or "new normal"?** What should the reader understand or be able to do after reading the article? This is the ultimate Resolution.

Based on your answers, I will propose a title and a "hook" for the introduction.

---

## Phase 2: The Outline (The Three Acts)

Once we agree on the core idea, I will create a detailed outline based on the Three-Act Structure:

### Act I: The Setup
-   **Hook:** Grab the reader's attention.
-   **Introduce the Problem:** State the central question or conflict.
-   **Establish the Stakes:** Explain why the reader should care.
-   **Thesis Statement:** Promise the reader what they will learn.

### Act II: The Exploration
-   **Point 1 (Rising Action):** The first major argument or piece of evidence.
-   **Point 2 (Obstacles):** Address counter-arguments, complexities, or common misconceptions.
-   **Point 3 (The Midpoint):** A key turning point or "aha!" moment in the argument.
-   **Point 4 (Escalation):** Deeper insights that build on the midpoint.

### Act III: The Resolution
-   **Climax (The Synthesis):** Present the main conclusion, tying all the points together.
-   **Falling Action (Practical Application):** Provide concrete examples, practical steps, or implications.
-   **The New Normal (The Call to Action):** State the key takeaway and what the reader should do or think now.

We will review and refine this outline before moving on.

---

## Phase 3: The Draft (The Writing)

With an approved outline, I will write the full draft of the article. I will focus on:
-   Following the narrative flow of the outline.
-   Maintaining a consistent tone and voice.
-   Using clear and engaging language.

---

## Phase 4: The Review (The Refinement)

Finally, I will perform an editorial review of the draft, checking for:
-   **Clarity and Flow:** Is the article easy to read and understand?
-   **Strength of Argument:** Is the narrative compelling and persuasive?
-   **Grammar and Style:** Are there any grammatical errors or stylistic issues?
-   **Impact:** Does the introduction hook the reader effectively? Does the conclusion provide a satisfying resolution?

I will provide a list of suggested revisions for your approval.


---

### Optionality Review — Evaluate design decisions for flexibility and reversibility

> Skill name: `optionality-review`

# Optionality Review

Review this [CODE/ARCHITECTURE/PLAN/DECISION] through the lens of strategic optionality.

(See Quick Reference section below for optionality principles and red/green flags)

## Work to Review

[PASTE YOUR WORK OR SPECIFY FILE PATH]

## Context (optional)

[Any relevant context: timeline, constraints, uncertainty level]

---

## Phase 1: Decision Classification

First, classify the key decisions using Bezos's framework:

**Type 1 (One-Way Doors):** Consequential and irreversible
- Require careful, methodical consideration
- Need broad consultation
- Examples: Core architecture, public APIs, major vendor commitments

**Type 2 (Two-Way Doors):** Changeable and reversible
- Should be made quickly with ~70% information
- Can be changed if wrong
- Examples: Internal tooling, feature flags, config choices

For each major decision in this work:

| Decision | Type | Reversibility | Decision Deadline | Justification |
|----------|------|---------------|-------------------|---------------|
| [What's being decided] | [1 or 2] | [EASY/MODERATE/HARD/IRREVERSIBLE] | [When must we decide?] | [Why this classification] |

**Early Exit:** If NO Type 1 decisions identified, output abbreviated report:
- List Type 2 decisions with brief notes
- Recommend: "Proceed quickly - all decisions are reversible"
- Skip Phases 2-6

---

## Phase 2: Alternative Paths

For Type 1 decisions, evaluate the option space (2-4 alternatives):

### Current Approach
- Description: [Brief summary]
- Locks in: [What future choices this constrains]
- Enables: [What this makes possible]

### Alternative A
- Description: [Different approach]
- Would preserve: [What options stay open]
- Trade-off: [What we'd give up]

### Alternative B (if applicable)
- Description: [Another approach]
- Would preserve: [What options stay open]
- Trade-off: [What we'd give up]

### Alternative C, D... (add more if needed for complex decisions)

**Assessment:** Are alternatives adequately explored? [YES/NO]
If NO, what should be investigated before committing?

**For Type 2 decisions:** Don't deep-dive. Briefly note 1-2 alternatives, then move on - speed matters more than exhaustive analysis for reversible decisions.

---

## Phase 3: Exit Costs & Escape Hatches

For Type 1 decisions from Phase 1, map the exit strategy:

| Decision | Reversal Cost | Reversal Time | Escape Hatch |
|----------|---------------|---------------|--------------|
| [Choice made] | [LOW/MED/HIGH] | [hours/days/weeks/months] | [Concrete path to undo if needed] |
| [Another choice] | [LOW/MED/HIGH] | [hours/days/weeks/months] | [How to exit] |

**Red Flags:**
- [ ] Irreversible decisions without clear justification
- [ ] No escape hatches for major commitments
- [ ] Assumptions treated as facts
- [ ] "We can refactor later" without a concrete path

**Reversibility Score:** [1-10] (10 = easily reversible)

---

## Phase 4: Failure Modes & Fallbacks

What if things go wrong?

| Failure Scenario | Probability | Impact | Fallback Plan | Recovery Cost |
|------------------|-------------|--------|---------------|---------------|
| [What could fail] | [L/M/H] | [L/M/H/CRITICAL] | [Plan B] | [time/effort] |

**External Dependencies:**
- [ ] Vendor lock-in: [None / Acceptable / Concerning]
- [ ] Technology bets: [Reversible / Locked]
- [ ] Regulatory assumptions: [Validated / Assumed]
- [ ] Single points of failure identified: [YES/NO]

**Resilience Score:** [1-10] (10 = multiple fallbacks, graceful degradation)

**Convergence Check:** If Reversibility ≥7 AND Resilience ≥7, consider skipping to Final Report.

---

## Phase 5: Future Value Assessment

Does this create or destroy options?

### Options CREATED
1. [New capability enabled]
   - Enables: [What becomes possible]
   - Value: [Why this matters]

2. [Another capability]
   - Enables: [What becomes possible]
   - Value: [Why this matters]

### Options DESTROYED (with justification)
1. [Closed off possibility]
   - Prevents: [What becomes harder/impossible]
   - Justified because: [Why trade-off is acceptable]

### Growth Potential
- Can scale to 10x: [YES/PARTIALLY/NO]
- Can add features without rewrite: [YES/PARTIALLY/NO]
- Can be extracted/reused: [YES/PARTIALLY/NO]
- Learning/telemetry built in: [YES/NO]

**Future Value Score:** [1-10] (10 = maximum option creation)

---

## Phase 6: Decision Points & Triggers

Where should we reassess?

| Milestone | What to Assess | Reassess Trigger | Go/No-Go Criteria |
|-----------|----------------|------------------|-------------------|
| [When] | [What we're evaluating] | [What would cause review] | [How to decide] |
| [Next milestone] | [Another assessment] | [Trigger condition] | [Decision criteria] |
| [Future checkpoint] | [Long-term assessment] | [Warning sign] | [How to decide] |

**Assumption Validation:**
- [ ] Key assumptions explicitly stated
- [ ] Validation checkpoints defined
- [ ] Early warning metrics identified

---

## Final Report

### Scores Summary
- Reversibility: [X/10]
- Resilience: [X/10]
- Future Value: [X/10]
- **Overall Optionality: [X/10]** (average, or lowest score if any ≤3)

### Verdict

**Optionality Assessment:** [FLEXIBLE | BALANCED | LOCKED_IN | CONCERNING]
- FLEXIBLE (8-10): Excellent strategic flexibility
- BALANCED (5-7): Acceptable trade-offs, some lock-in justified
- LOCKED_IN (3-4): Significant constraints, ensure they're intentional
- CONCERNING (1-2): High risk, reconsider approach

**Key Findings:**
1. [Most significant optionality issue or strength]
2. [Second finding]
3. [Third finding]

### Recommendations

**Before proceeding:**
- [Critical actions to preserve flexibility]

**Build in over time:**
- [Strategic improvements for future flexibility]

### The Bottom Line

[2-3 sentences: Is the level of lock-in appropriate for our uncertainty level? Are we preserving the right options? What's the key trade-off?]

**Human review recommended:** [YES/NO]
**Reason:** [Why human judgment needed, or why assessment is sufficient]


---

### Multi-Agent Parallel Review — Coordinate multiple agents for comprehensive review

> Skill name: `multi-agent-review`

I need a comprehensive multi-agent parallel code review using the Wave/Gate architecture.

CODE TO REVIEW:
[paste code or specify: "Review all files in src/auth/"]

ARCHITECTURE:
Wave 1 (Parallel) → Gate 1 (Sequential) → Wave 2 (Parallel) → Gate 2 (Sequential) → Wave 3 (Sequential)

Execute this workflow:

═══════════════════════════════════════════════════════════════
WAVE 1: PARALLEL INDEPENDENT ANALYSIS
═══════════════════════════════════════════════════════════════

Launch 5 parallel tasks. Each task is independent and can run simultaneously.

TASK 1: Security Review
Role: Security Engineer
Focus:
- OWASP Top 10 vulnerabilities
- Input validation and sanitization
- Authentication and authorization flaws
- SQL injection, XSS, CSRF, SSRF
- Secret management and data exposure
- API security and rate limiting
- Cryptography usage

Output JSON format:
{
  "issues": [
    {
      "id": "SEC-001",
      "severity": "CRITICAL|HIGH|MEDIUM|LOW",
      "category": "authentication|input-validation|data-exposure|cryptography",
      "cwe_id": "CWE-XXX",
      "location": "file.js:line",
      "description": "Detailed description",
      "attack_vector": "How an attacker could exploit this",
      "recommendation": "Specific fix with code example"
    }
  ],
  "security_score": 0-3,
  "summary": "One-line summary"
}

TASK 2: Performance Review
Role: Performance Engineer
Focus:
- Time complexity (O(n²), O(n³) patterns)
- Database queries (N+1, missing indexes, full table scans)
- Memory allocation and leaks
- Unnecessary loops and iterations
- Caching opportunities
- Blocking I/O operations
- Resource pooling

TASK 3: Maintainability Review
Role: Future Developer (6 months out, original author gone)
Focus:
- Code clarity and readability
- Documentation (comments, docstrings, README)
- Pattern consistency across codebase
- Naming conventions (clear, descriptive)
- Technical debt indicators
- DRY violations
- Magic numbers and hard-coded values
- Complex conditionals

TASK 4: Requirements Validation
Role: QA Engineer
Focus:
- Requirements coverage (are all requirements implemented?)
- Edge case handling
- Test coverage gaps
- Behavioral correctness
- Missing functionality
- Acceptance criteria satisfaction

TASK 5: Operations Review
Role: SRE (on-call at 3am when this breaks)
Focus:
- Failure modes and error handling
- Observability (logging, metrics, tracing)
- Timeout and retry logic
- Circuit breakers and graceful degradation
- Resource management (connections, files, memory)
- Deployment/rollback complexity
- Configuration management
- Health checks and readiness probes

═══════════════════════════════════════════════════════════════
GATE 1: CONFLICT RESOLUTION (Wait for all Wave 1 tasks)
═══════════════════════════════════════════════════════════════

After all 5 tasks complete, consolidate findings:

TASK 6: Consolidation
Role: Senior Technical Lead

Tasks:
1. DEDUPLICATE ISSUES
   - Same issue reported by multiple reviewers → merge
   - Similar issues → merge if same root cause
   - Different perspectives on same code → keep separate if addressing different concerns

2. RESOLVE SEVERITY CONFLICTS
   Rules:
   - Security CRITICAL always wins
   - Take highest severity if 2+ reviewers agree it's a problem
   - Downgrade if only 1 reviewer flagged and others cleared

3. CALCULATE CONFIDENCE
   - Found by 1 reviewer: confidence = 0.60
   - Found by 2 reviewers: confidence = 0.80
   - Found by 3+ reviewers: confidence = 0.95
   - Severity disagreement: reduce confidence by 0.15

4. IDENTIFY CROSS-CUTTING CONCERNS
   - Issues affecting multiple domains
   - Systemic patterns (same problem in multiple places)

═══════════════════════════════════════════════════════════════
WAVE 2: PARALLEL CROSS-VALIDATION
═══════════════════════════════════════════════════════════════

Launch 2-3 parallel tasks reviewing the consolidated findings.

TASK 7: Meta-Review
Role: Quality Control Lead

Check:
1. COVERAGE GAPS - What wasn't examined?
2. FALSE POSITIVES - Are flagged issues actually problems?
3. SEVERITY CALIBRATION - Are CRITICAL ratings actually critical?
4. REVIEWER QUALITY - Did reviewers follow their focus areas?
5. SYSTEMIC PATTERNS - Do issues indicate deeper architectural problems?

TASK 8: Integration Analysis
Role: Systems Architect

Check for:
- System-wide impacts of issues
- Cascading failure scenarios
- Service dependency problems
- Data flow issues across boundaries

═══════════════════════════════════════════════════════════════
GATE 2: FINAL SYNTHESIS (Wait for Wave 2)
═══════════════════════════════════════════════════════════════

TASK 9: Final Report

Generate:
1. EXECUTIVE SUMMARY
   - Total issues by severity
   - Blockers (CRITICAL issues that prevent merge/deploy)
   - Key systemic issues

2. PRIORITIZED ACTION LIST
   - Must fix before merge (CRITICAL)
   - Should fix before deploy (HIGH)
   - Can fix later (MEDIUM/LOW)

3. BLOCKING ASSESSMENT
   - BLOCKS MERGE: Has CRITICAL issues
   - BLOCKS DEPLOY: Has HIGH operational risks
   - APPROVED: Ready for production
   - APPROVED_WITH_NOTES: Deploy with monitoring plan

4. CONVERGENCE METRICS
   - Number of issues found: CRITICAL/HIGH/MEDIUM/LOW
   - Confidence level: X% high-confidence issues
   - False positive estimate: X%
   - Coverage assessment: X% of code reviewed thoroughly

═══════════════════════════════════════════════════════════════
WAVE 3: CONVERGENCE CHECK
═══════════════════════════════════════════════════════════════

Determine if another iteration is needed:

CONVERGED if:
- new_critical_count == 0 AND
- new_issue_rate < 0.10 AND
- false_positive_rate < 0.20

ESCALATE_TO_HUMAN if:
- iteration >= 3 OR
- Found conflicting CRITICAL issues OR
- Uncertain about severity

ITERATE if:
- new_critical_count > 0 OR
- new_issue_rate >= 0.10

If ITERATE: Start Wave 1 again focusing only on CRITICAL and HIGH issues.


---

### Plan Review — Iterative review of implementation plans

> Skill name: `plan-review`

# Iterative Plan Review (Rule of 5)

Perform thorough implementation plan review using the Rule of 5 - iterative refinement until convergence.

## Setup

**If plan path provided:** Read the plan completely

**If no plan path:** Ask for the plan path or list available plans from `plans/`

## Process

Perform 5 passes, each focusing on different aspects. After each pass (starting with pass 2), check for convergence.

### PASS 1 - Feasibility & Risk

**Focus on:**
- Technical feasibility of proposed changes
- Identified risks and their mitigations
- Dependencies on external factors (APIs, services, libraries)
- Assumptions that need validation
- Potential blockers not addressed
- Resource requirements (time, expertise, infrastructure)

**Output format:**
```
PASS 1: Feasibility & Risk

Issues Found:

[FEAS-001] [CRITICAL|HIGH|MEDIUM|LOW] - Phase/Section
Description: [What's wrong]
Evidence: [Why this is a problem]
Recommendation: [How to fix with specific guidance]

[FEAS-002] ...
```

**What to look for:**
- "We'll just..." statements hiding complexity
- External dependencies assumed to be available
- Time estimates that seem unrealistic
- Required expertise not accounted for
- Breaking changes not acknowledged
- Rollback strategy missing or inadequate

### PASS 2 - Completeness & Scope

**Focus on:**
- Missing phases or steps
- Undefined or vague success criteria
- Gaps between current and desired state
- "Out of Scope" clearly defined
- All affected files/components identified
- Testing strategy covers all scenarios
- Edge cases considered

**Prefix:** COMP-001, COMP-002, etc.

**What to look for:**
- "And then..." without the "then" being in the plan
- Success criteria that can't be verified
- Missing integration points
- Unclear handoff points between phases
- Scope creep hiding in vague language

### PASS 3 - Spec & TDD Alignment

**Focus on:**
- Links to spec files (if applicable)
- Tests planned before implementation (TDD)
- Success criteria are testable
- Test-first approach clear in each phase
- All requirements from specs covered
- Verification steps defined

**Prefix:** TDD-001, TDD-002, etc.

**What to look for:**
- "We'll test it" without specific test descriptions
- Implementation before tests in phase sequence
- Untestable success criteria ("works well", "is fast")
- Missing test coverage for error cases
- No mention of what tests to write

### PASS 4 - Ordering & Dependencies

**Focus on:**
- Phases in correct order (can't do B before A)
- Dependencies between phases clearly stated
- Parallelizable work identified
- Critical path identified
- Each phase can be independently verified
- Rollback/reversal possible at phase boundaries

**Prefix:** ORD-001, ORD-002, etc.

**What to look for:**
- Phase 2 requires Phase 3 to be done first
- Circular dependencies between phases
- "Big bang" integration at the end
- No incremental verification
- All-or-nothing approach

### PASS 5 - Clarity & Executability

**Focus on:**
- Specific enough for someone else to implement
- File paths and changes are concrete
- No ambiguous instructions
- Clear what "done" means for each phase
- Technical terms defined or understood
- Handoff points between phases clear

**Prefix:** EXEC-001, EXEC-002, etc.

**What to look for:**
- "Update the authentication" - update how? where?
- "Make it work with..." - what does "work" mean?
- "Refactor as needed" - refactor what? when?
- File paths missing or vague
- Assumptions about shared knowledge

## Convergence Check

After each pass (starting with pass 2), report:

```
Convergence Check After Pass [N]:

1. New CRITICAL issues: [count]
2. Total new issues this pass: [count]
3. Total new issues previous pass: [count]
4. Estimated false positive rate: [percentage]

Status: [CONVERGED | ITERATE | NEEDS_HUMAN]
```

**Convergence criteria:**
- **CONVERGED**: No new CRITICAL, <10% new issues vs previous pass, <20% false positives
- **ITERATE**: Continue to next pass
- **NEEDS_HUMAN**: Found blocking issues requiring human judgment

**If CONVERGED before Pass 5:** Stop and report final findings.

## Final Report

After convergence or completing all passes:

```
## Plan Review Final Report

**Plan:** plans/[filename].md

### Summary

Total Issues by Severity:
- CRITICAL: [count] - Must fix before implementation
- HIGH: [count] - Should fix before implementation
- MEDIUM: [count] - Consider addressing
- LOW: [count] - Nice to have

Convergence: Pass [N]

### Top 3 Most Critical Findings

1. [FEAS-001] [Description] - Phase [N]
   Impact: [Why this matters]
   Fix: [What to do]

2. [COMP-003] [Description] - Phase [N]
   Impact: [Why this matters]
   Fix: [What to do]

3. [TDD-002] [Description] - Phase [N]
   Impact: [Why this matters]
   Fix: [What to do]

### Recommended Next Actions

1. [Action 1 - specific and actionable]
2. [Action 2 - specific and actionable]
3. [Action 3 - specific and actionable]

### Verdict

[READY_TO_IMPLEMENT | NEEDS_REVISION | NEEDS_MORE_RESEARCH]

**Rationale:** [1-2 sentences explaining the verdict]
```

## Rules

1. **Be specific** - Reference plan sections/phases, provide file:line if relevant
2. **Provide actionable fixes** - Don't just say "add more detail", say what detail
3. **Validate claims** - Don't flag potential issues, confirm they exist
4. **Prioritize correctly**:
   - CRITICAL: Blocks implementation or will cause failure
   - HIGH: Significantly impacts quality or feasibility
   - MEDIUM: Worth addressing but not blocking
   - LOW: Minor improvements
5. **If converged before pass 5** - Stop and report, don't continue needlessly


---

### Design Artifact Review — Review problem statements and decision matrices

> Skill name: `design-review`

# Design Artifact Review

Review design artifacts for rigor, completeness, and adherence to Design in Practice principles.

## Setup

**If artifact path provided:** Read the artifact completely
**If no path:** Ask which artifact to review, or list available design documents

## Review Framework

Perform targeted review based on artifact type. Each review checks for common failure modes that lead to poor solutions.

---

## ARTIFACT TYPE: Problem Statement

### Check 1: Solution Contamination

**Question:** Does the problem statement contain or imply solutions?

**Red flags:**
- "We need to..." (solution language)
- Technology names (Redis, Kafka, etc.) unless they ARE the problem
- "Add", "implement", "create", "build" verbs
- Comparison to how other systems work

**Test:** Could multiple fundamentally different solutions address this statement?
- YES → Good problem statement (solution-agnostic)
- NO → Solution is embedded, rewrite needed

**Output:**
```
Solution Contamination: [CLEAN | CONTAMINATED]

Evidence:
- [Quote from statement showing contamination, or "None found"]

Recommendation:
- [How to remove solution language]
```

### Check 2: Root Cause vs. Symptom

**Question:** Does this describe the mechanism, or just the observable effect?

**Symptom language:**
- "Users experience..."
- "The system is slow/broken/failing..."
- "Errors occur when..."

**Mechanism language:**
- "Because X happens, Y results in Z"
- "The [component] does [action] which causes [effect]"
- Clear causal chain

**Test:** Ask "Why?" - if there's a deeper answer, this is a symptom.

**Output:**
```
Root Cause Analysis: [MECHANISM | SYMPTOM | UNCLEAR]

Depth check:
- Statement says: [quote]
- Ask "Why?": [deeper cause if exists]
- Assessment: [Is this the root or just a layer?]

Recommendation:
- [How to dig deeper, or "Root cause identified"]
```

### Check 3: Specificity

**Question:** Is the problem precise enough to guide solution selection?

**Vague indicators:**
- "Performance issues" (which metric? what threshold?)
- "Users are confused" (which users? confused about what?)
- "The code is messy" (what aspect? what's the impact?)

**Specific indicators:**
- Quantified thresholds ("response time > 2s")
- Named components ("SessionManager.close()")
- Reproducible conditions ("when concurrent users > 50")

**Output:**
```
Specificity: [PRECISE | VAGUE | MIXED]

Vague elements:
- [Element 1]: [How to make specific]
- [Element 2]: [How to make specific]

Missing specifics:
- [What metric/threshold/condition is unclear]
```

### Check 4: Evidence Quality

**Question:** Is the diagnosis based on verified facts or assumptions?

**Look for:**
- Evidence cited for each claim
- Ruled-out alternatives documented
- Hypothesis testing described
- Data sources referenced

**Output:**
```
Evidence Quality: [VERIFIED | ASSUMED | MIXED]

Claims without evidence:
- [Claim 1]: [What evidence is needed]
- [Claim 2]: [What evidence is needed]

Ruled-out alternatives:
- [Listed? How many? Are they reasonable alternatives?]
```

### Check 5: The Obvious Solution Test

**Question:** Does the solution feel obvious after reading this statement?

If the reader finishes the problem statement and doesn't immediately think "oh, we should do X", the diagnosis is incomplete.

**Output:**
```
Obvious Solution Test: [PASS | FAIL | PARTIAL]

After reading, the obvious action is: [What seems like the right solution]

If FAIL:
- What's unclear: [What question remains]
- What's missing: [What would make it obvious]
```

### Problem Statement Verdict

```
## Problem Statement Review Summary

| Check | Result | Action Needed |
|-------|--------|---------------|
| Solution Contamination | [CLEAN/CONTAMINATED] | [Action or "None"] |
| Root Cause | [MECHANISM/SYMPTOM] | [Action or "None"] |
| Specificity | [PRECISE/VAGUE] | [Action or "None"] |
| Evidence | [VERIFIED/ASSUMED] | [Action or "None"] |
| Obvious Solution | [PASS/FAIL] | [Action or "None"] |

**Verdict:** [READY_FOR_DIRECTION | NEEDS_REVISION | BACK_TO_DESCRIBE]

**Top Issue:** [Most critical thing to fix]

**Recommended Action:** [Specific next step]
```

---

## ARTIFACT TYPE: Decision Matrix

### Check 1: Status Quo Baseline

**Question:** Is "do nothing" the first column?

The Status Quo:
- Provides baseline for comparison
- Forces articulation of current state costs
- Prevents "solution in search of problem"

**Output:**
```
Status Quo Baseline: [PRESENT | MISSING]

If missing:
- Impact: Cannot compare alternatives to current state
- Fix: Add Status Quo column with honest assessment
```

### Check 2: Fact vs. Judgment Separation

**Question:** Is cell text factual and neutral, with judgment shown separately?

**Contaminated cells:**
- "Good performance" (judgment as text)
- "Easy to implement" (subjective)
- "Better than X" (comparative judgment)

**Clean cells:**
- "< 10ms p99 latency" (measurable fact)
- "Requires changes to 3 files" (countable)
- "Uses existing auth pattern" (verifiable)

**Output:**
```
Fact/Judgment Separation: [CLEAN | CONTAMINATED]

Contaminated cells:
| Row | Column | Current Text | Factual Rewrite |
|-----|--------|--------------|-----------------|
| [Row] | [Col] | "[Text]" | "[Suggestion]" |

Assessment indicators:
- Are judgments (good/bad) shown via color/symbol, not text? [YES/NO]
```

### Check 3: Criteria Completeness

**Question:** Are all relevant trade-off dimensions represented?

**Common missing criteria:**
- Maintenance burden (long-term cost)
- Rollback difficulty (reversibility)
- Team expertise (can we actually do this?)
- Integration complexity (how it affects other systems)
- Failure modes (what happens when it breaks?)

**Output:**
```
Criteria Completeness: [COMPLETE | GAPS]

Present criteria: [List]

Potentially missing:
- [Criterion]: [Why it matters for this decision]
- [Criterion]: [Why it matters for this decision]

Recommendation:
- [Which criteria to add]
```

### Check 4: Approach Diversity

**Question:** Are the approaches fundamentally different, or variations of the same idea?

**Insufficient diversity:**
- "Option A: Use Redis" / "Option B: Use Memcached" (same category)
- All options involve adding something (no "remove feature" option)
- All options are technical (no process/product options)

**Good diversity:**
- Different architectural approaches
- Build vs. Buy vs. Remove
- Technical vs. Process vs. Product solutions

**Output:**
```
Approach Diversity: [DIVERSE | SIMILAR]

Approaches listed:
- [Approach 1]: [Category]
- [Approach 2]: [Category]
- [Approach 3]: [Category]

Missing perspectives:
- [What category of solution wasn't considered]
```

### Check 5: Cell Verification

**Question:** Are the facts in the matrix verifiable and accurate?

Spot-check 2-3 claims:
- Can this be verified in the codebase?
- Is this number accurate?
- Is this comparison fair?

**Output:**
```
Cell Verification: [VERIFIED | UNVERIFIED | ERRORS]

Spot checks:
- [Cell Row/Col]: [Claim] → [Verification result]
- [Cell Row/Col]: [Claim] → [Verification result]

Errors found:
- [Cell]: [What's wrong and what's correct]
```

### Decision Matrix Verdict

```
## Decision Matrix Review Summary

| Check | Result | Action Needed |
|-------|--------|---------------|
| Status Quo Baseline | [PRESENT/MISSING] | [Action or "None"] |
| Fact/Judgment Separation | [CLEAN/CONTAMINATED] | [Action or "None"] |
| Criteria Completeness | [COMPLETE/GAPS] | [Action or "None"] |
| Approach Diversity | [DIVERSE/SIMILAR] | [Action or "None"] |
| Cell Verification | [VERIFIED/ERRORS] | [Action or "None"] |

**Verdict:** [READY_FOR_DECISION | NEEDS_REVISION | NEEDS_MORE_OPTIONS]

**Selected approach justified?** [YES/NO - Is the rationale sound?]

**Top Issue:** [Most critical thing to fix]

**Recommended Action:** [Specific next step]
```

---

## ARTIFACT TYPE: Scope Document (Delimit Phase)

### Check 1: Explicit Non-Goals

**Question:** Are out-of-scope items explicitly listed?

Scope creep happens when boundaries are implicit. Explicit non-goals:
- Prevent "while we're in there" additions
- Set expectations with stakeholders
- Provide reference when scope questions arise

**Output:**
```
Non-Goals: [EXPLICIT | IMPLICIT | MISSING]

Listed non-goals: [count]

Likely scope creep vectors not addressed:
- [Related item that might get added]
- [Adjacent problem that might expand scope]
```

### Check 2: Constraint Realism

**Question:** Are the constraints achievable and honest?

Look for:
- Conflicting constraints ("fast AND cheap AND complete")
- Unstated constraints (timeline, budget, expertise)
- Over-optimistic assumptions

**Output:**
```
Constraints: [REALISTIC | OPTIMISTIC | CONFLICTING]

Constraint conflicts:
- [Constraint A] vs [Constraint B]: [Why they conflict]

Missing constraints:
- [What's unstated but will affect the work]
```

---

## COMBINED REVIEW (Full Design Package)

When reviewing Problem Statement + Decision Matrix + Plan together:

### Alignment Check

1. **Problem → Direction alignment:**
   - Does the selected approach actually address the diagnosed problem?
   - Or does it solve a different/adjacent problem?

2. **Scope → Plan alignment:**
   - Does the plan stay within stated scope?
   - Are non-goals respected in the implementation?

3. **Decision rationale → Plan execution:**
   - Does the plan leverage the reasons the approach was chosen?
   - Are accepted trade-offs reflected in implementation?

**Output:**
```
## Alignment Review

Problem → Direction: [ALIGNED | DRIFT]
- [Evidence of alignment or drift]

Scope → Plan: [ALIGNED | CREEP]
- [Evidence of scope adherence or creep]

Decision → Plan: [ALIGNED | INCONSISTENT]
- [Does plan execute on decision rationale?]
```

---

## Final Report Template

```
## Design Artifact Review Report

**Artifact(s) Reviewed:** [List]
**Date:** [YYYY-MM-DD]

### Summary

| Artifact | Verdict | Key Issues |
|----------|---------|------------|
| Problem Statement | [READY/REVISION/BACK] | [Top issue] |
| Decision Matrix | [READY/REVISION/MORE] | [Top issue] |
| Scope Document | [READY/REVISION] | [Top issue] |
| Alignment | [ALIGNED/DRIFT] | [Top issue] |

### Critical Findings

1. **[ARTIFACT-CHECK]** [Severity]
   - Issue: [What's wrong]
   - Impact: [Why it matters]
   - Fix: [Specific action]

2. **[ARTIFACT-CHECK]** [Severity]
   - Issue: [What's wrong]
   - Impact: [Why it matters]
   - Fix: [Specific action]

### Recommended Actions

1. [Most important action]
2. [Second action]
3. [Third action]

### Overall Verdict

[PROCEED_TO_IMPLEMENTATION | REVISE_ARTIFACTS | RETURN_TO_EARLIER_PHASE]

**Rationale:** [1-2 sentences]
```


---

### Research Review — Iterative review of research documents using Rule of 5

> Skill name: `research-review`

# Iterative Research Review (Rule of 5)

Perform thorough research document review using the Rule of 5 - iterative refinement until convergence.

## Setup

**If research document path provided:** Read the document completely

**If no path:** Ask for the research document path or list available research documents

## Process

Perform 5 passes, each focusing on different aspects. After each pass (starting with pass 2), check for convergence.

### PASS 1 - Accuracy & Sources

**Focus on:**
- Claims backed by evidence
- Source credibility and recency
- Correct interpretation of sources
- Factual accuracy of technical details
- Version/date relevance (is information outdated?)
- Code references are correct (file:line exist and match claim)

**Output format:**
```
PASS 1: Accuracy & Sources

Issues Found:

[ACC-001] [CRITICAL|HIGH|MEDIUM|LOW] - Section/Paragraph
Description: [What's inaccurate or unsourced]
Evidence: [Why this is problematic]
Recommendation: [How to fix with specific guidance]

[ACC-002] ...
```

**What to look for:**
- "This works by..." without code reference
- Claims about codebase without verification
- Outdated information (library versions, deprecated APIs)
- Misinterpretation of source code
- Assumptions presented as facts

### PASS 2 - Completeness & Scope

**Focus on:**
- Missing important topics or considerations
- Unanswered questions that should be addressed
- Gaps in the analysis
- Scope creep (irrelevant tangents)
- Depth appropriate for the topic
- All research questions answered

**Prefix:** COMP-001, COMP-002, etc.

**What to look for:**
- Research question asked but not answered
- Obvious related topics not explored
- Shallow treatment of complex topics
- Too much detail on tangential topics
- "Further research needed" without followthrough

### PASS 3 - Clarity & Structure

**Focus on:**
- Logical flow and organization
- Clear definitions of terms
- Appropriate headings and sections
- Readability for target audience
- Jargon explained or avoided
- Consistent terminology

**Prefix:** CLAR-001, CLAR-002, etc.

**What to look for:**
- Jumping between topics without transitions
- Technical terms used without definition
- Conclusions before supporting evidence
- Redundant sections
- Confusing or ambiguous language

### PASS 4 - Actionability & Conclusions

**Focus on:**
- Clear takeaways and recommendations
- Conclusions supported by the research
- Practical applicability to the project
- Trade-offs clearly articulated
- Next steps identified
- Decision-making guidance provided

**Prefix:** ACT-001, ACT-002, etc.

**What to look for:**
- Research without recommendations
- Conclusions that don't follow from findings
- "Interesting but..." without actionable insight
- Missing implementation guidance
- No clear "what should we do?"

### PASS 5 - Integration & Context

**Focus on:**
- Alignment with existing research
- Connections to specs and requirements
- Relevance to current project goals
- Contradictions with established decisions
- Impact on existing plans
- References to related work

**Prefix:** INT-001, INT-002, etc.

**What to look for:**
- Contradicts previous research without acknowledgment
- Ignores existing patterns in codebase
- Doesn't reference related specs or docs
- Recommendations conflict with project direction
- Missing cross-references

## Convergence Check

After each pass (starting with pass 2), report:

```
Convergence Check After Pass [N]:

1. New CRITICAL issues: [count]
2. Total new issues this pass: [count]
3. Total new issues previous pass: [count]
4. Estimated false positive rate: [percentage]

Status: [CONVERGED | ITERATE | NEEDS_HUMAN]
```

**Convergence criteria:**
- **CONVERGED**: No new CRITICAL, <10% new issues vs previous pass, <20% false positives
- **ITERATE**: Continue to next pass
- **NEEDS_HUMAN**: Found blocking issues requiring human judgment

**If CONVERGED before Pass 5:** Stop and report final findings.

## Final Report

After convergence or completing all passes:

```
## Research Review Final Report

**Research:** [path/to/research.md]

### Summary

Total Issues by Severity:
- CRITICAL: [count] - Must fix before using research
- HIGH: [count] - Should fix before using research
- MEDIUM: [count] - Consider addressing
- LOW: [count] - Nice to have

Convergence: Pass [N]

### Top 3 Most Critical Findings

1. [ACC-001] [Description] - Section [N]
   Impact: [Why this matters]
   Fix: [What to do]

2. [COMP-003] [Description] - Section [N]
   Impact: [Why this matters]
   Fix: [What to do]

3. [ACT-002] [Description] - Conclusions
   Impact: [Why this matters]
   Fix: [What to do]

### Recommended Revisions

1. [Action 1 - specific and actionable]
2. [Action 2 - specific and actionable]
3. [Action 3 - specific and actionable]

### Verdict

[READY | NEEDS_REVISION | NEEDS_MORE_RESEARCH]

**Rationale:** [1-2 sentences explaining the verdict]

### Research Quality Assessment

- **Accuracy**: [Excellent|Good|Fair|Poor] - [brief comment]
- **Completeness**: [Excellent|Good|Fair|Poor] - [brief comment]
- **Actionability**: [Excellent|Good|Fair|Poor] - [brief comment]
- **Clarity**: [Excellent|Good|Fair|Poor] - [brief comment]
```

## Rules

1. **Be specific** - Reference sections/paragraphs, provide file:line for code claims
2. **Verify claims** - Actually check code references and factual statements
3. **Validate actionability** - Research should drive decisions, not just inform
4. **Prioritize correctly**:
   - CRITICAL: Factually wrong or misleading
   - HIGH: Significant gaps or unclear conclusions
   - MEDIUM: Could be clearer or more complete
   - LOW: Minor improvements
5. **If converged before pass 5** - Stop and report, don't continue needlessly


---

### Issue Tracker Review — Review issues for completeness and dependencies

> Skill name: `issue-review`

# Iterative Issue Tracker Review (Rule of 5)

Perform thorough issue review using the Rule of 5 - iterative refinement until convergence.

## Setup

### Gathering Issues to Review

**For Beads:**
```bash
bd list                    # All issues
bd ready                   # Unblocked issues
bd graph                   # Dependency visualization
bd show <id>               # Individual issue details
bd dep tree                # Dependency tree
bd dep cycles              # Check for circular dependencies
```

**For GitHub Issues:**
```bash
gh issue list --label "needs-review" --json number,title,body,labels
gh issue view <number>
```

**For other systems:**
- Export issues to JSON/CSV
- Use API or CLI tools
- Provide issue data as input

## Process

Perform 5 passes, each focusing on different aspects. After each pass (starting with pass 2), check for convergence.

### PASS 1 - Completeness & Clarity

**Focus on:**
- Title clearly describes the work
- Description has enough context to implement
- File paths and changes are concrete (not vague)
- Success criteria or tests are defined
- No ambiguous or vague language
- Acceptance criteria clear

**Output format:**
```
PASS 1: Completeness & Clarity

Issues Found:

[CLRT-001] [CRITICAL|HIGH|MEDIUM|LOW] - Issue ID/Number
Title: [Issue title]
Description: [What's unclear or incomplete]
Evidence: [Why this is a problem]
Recommendation: [How to fix - specific command or action]

[CLRT-002] ...
```

**What to look for:**
- Vague titles: "Fix auth" (fix what?)
- No description or minimal description
- "Implement X" without saying how or where
- Missing file paths
- No verification steps
- Unclear done criteria

**For Beads:**
```bash
# Fix issues found
bd edit <id> description     # Update description
bd update <id> --title="New clear title"
```

**For GitHub:**
```bash
gh issue edit <number> --title "New title"
gh issue edit <number> --body "New description"
```

### PASS 2 - Scope & Atomicity

**Focus on:**
- Each issue represents one logical unit of work
- Issues not too large (should complete in one session)
- Issues not too small (trivial changes bundled appropriately)
- Clear boundaries between issues
- No overlapping scope between issues
- Each issue independently valuable

**Prefix:** SCOPE-001, SCOPE-002, etc.

**What to look for:**
- "Implement entire authentication system" (too large)
- "Fix typo in README line 42" (maybe too small, could bundle)
- Two issues both say "update user model"
- Issue requires changes across 10+ files
- Issue mixes refactoring with feature work

**For Beads:**
```bash
# Split large issues
bd create --title="Phase 1: ..." --description="..."
bd create --title="Phase 2: ..." --description="..."
bd dep add phase2-id phase1-id  # phase2 depends on phase1

# Merge small issues
bd close small-issue-1 --reason="merged into main-issue"
bd update main-issue --description="Now includes work from small-issue-1"
```

### PASS 3 - Dependencies & Ordering

**Focus on:**
- Dependencies correctly defined
- No missing dependencies (B needs A but not linked)
- No circular dependencies (A→B→C→A)
- Critical path is sensible
- Parallelizable work not falsely serialized
- Dependency rationale is clear

**Prefix:** DEP-001, DEP-002, etc.

**What to look for:**
- Issue requires another to be done but not linked
- Circular dependency chains
- Everything depends on one issue (bottleneck)
- No dependencies when clear order exists
- Dependencies prevent parallel work unnecessarily

**For Beads:**
```bash
# Check for problems
bd dep cycles                           # Find circular dependencies
bd dep tree                            # Visualize dependencies

# Fix dependencies
bd dep add <blocked-id> <blocker-id>   # Add missing dependency
bd dep remove <blocked-id> <blocker-id> # Remove incorrect dependency
```

**For GitHub:**
```bash
# Use labels and issue references
gh issue edit <number> --add-label "blocked-by-#123"
# Or reference in description: "Depends on #123"
```

### PASS 4 - Plan & Spec Alignment

**Focus on:**
- Issues trace back to plan phases
- Plan references in descriptions
- Related specs linked where applicable
- TDD approach clear (tests defined before impl)
- All plan phases have corresponding issues
- Issue breakdown matches plan structure

**Prefix:** ALIGN-001, ALIGN-002, etc.

**What to look for:**
- Plan has 5 phases but only 3 issues
- Issue doesn't reference source plan
- Plan says "test first" but issue doesn't mention tests
- Spec requirements not covered by any issue
- Issue contradicts plan approach

**For Beads:**
```bash
# Add plan reference
bd update <id> --description="...

Ref: plans/2026-01-12-feature.md#phase-2"
```

**For GitHub:**
```bash
gh issue edit <number> --body "...

Related Plan: `plans/2026-01-12-feature.md#phase-2`"
```

### PASS 5 - Executability & Handoff

**Focus on:**
- Can be picked up by any developer/agent
- No implicit knowledge required
- Verification steps clear and specific
- Handoff points defined for multi-issue work
- Priority and labels appropriate
- Estimation realistic (if used)

**Prefix:** EXEC-001, EXEC-002, etc.

**What to look for:**
- "You know what to do" (no, they don't)
- Assumes knowledge of previous conversations
- "Test it" without saying how
- No verification steps
- Priority/labels missing or incorrect

## Convergence Check

After each pass (starting with pass 2), report:

```
Convergence Check After Pass [N]:

1. New CRITICAL issues: [count]
2. Total new issues this pass: [count]
3. Total new issues previous pass: [count]
4. Estimated false positive rate: [percentage]

Status: [CONVERGED | ITERATE | NEEDS_HUMAN]
```

**Convergence criteria:**
- **CONVERGED**: No new CRITICAL, <10% new issues vs previous pass, <20% false positives
- **ITERATE**: Continue to next pass
- **NEEDS_HUMAN**: Found blocking issues requiring human judgment

**If CONVERGED before Pass 5:** Stop and report final findings.

## Final Report

After convergence or completing all passes:

```
## Issue Tracker Review Final Report

**System:** [Beads/GitHub/Linear/Jira]
**Scope:** [All issues / Milestone X / Labels Y]

### Summary

Total Issues Reviewed: [count]

Issues Found by Severity:
- CRITICAL: [count] - Must fix before work starts
- HIGH: [count] - Should fix before work starts
- MEDIUM: [count] - Consider addressing
- LOW: [count] - Nice to have

Convergence: Pass [N]

### Top 3 Most Critical Findings

1. [DEP-001] Circular dependency detected
   Issues: #42 → #43 → #44 → #42
   Impact: Cannot start any of these issues
   Fix: `bd dep remove 42 44` to break cycle

2. [SCOPE-002] Issue too large to complete
   Issue: #38 "Implement authentication system"
   Impact: Unmanageable scope, blocks other work
   Fix: Split into 5 issues for each plan phase

3. [CLRT-003] Missing implementation details
   Issue: #29 "Update API"
   Impact: Cannot implement without more info
   Fix: Add file paths, endpoints, and success criteria

### Recommended Actions

Provide specific commands for fixes:

**Beads Commands:**
```bash
# Fix circular dependency
bd dep remove 42 44

# Split large issue
bd create --title="Phase 1: Auth tokens" --description="..."
bd create --title="Phase 2: Auth middleware" --description="..."
bd dep add phase2-id phase1-id
bd close 38 --reason="split into phase issues"

# Update missing details
bd edit 29 description
# Then add: Files: api/routes.ts, api/handlers.ts; Tests: api/routes.test.ts
```

**GitHub Commands:**
```bash
gh issue edit 29 --body "...

Files to change:
- api/routes.ts
- api/handlers.ts
- api/routes.test.ts

Success criteria:
- [ ] Tests pass
- [ ] Endpoints return correct status codes"
```

### Verdict

[READY_TO_WORK | NEEDS_UPDATES | NEEDS_REPLANNING]

**Rationale:** [1-2 sentences explaining the verdict]

### Issue Quality Assessment

- **Clarity**: [Excellent|Good|Fair|Poor] - [brief comment]
- **Scope**: [Excellent|Good|Fair|Poor] - [brief comment]
- **Dependencies**: [Excellent|Good|Fair|Poor] - [brief comment]
- **Completeness**: [Excellent|Good|Fair|Poor] - [brief comment]
```

## Rules

1. **Reference specific issues** - Use issue IDs/numbers precisely
2. **Provide actionable commands** - Show exact commands to fix issues
3. **Check actual content** - Don't assume, verify with issue details
4. **Prioritize correctly**:
   - CRITICAL: Blocks all work (circular deps, missing info)
   - HIGH: Blocks specific work or causes confusion
   - MEDIUM: Could be clearer but workable
   - LOW: Minor improvements
5. **If converged before pass 5** - Stop and report


---

### Universal Rule of 5 Review — Steve Yegge's original 5-stage review for any artifact

> Skill name: `rule-of-5-universal`

# Universal Rule of 5 Review

Review this [CODE/PLAN/RESEARCH/ISSUE/SPEC/DOCUMENT] using Steve Yegge's Rule of 5 - five stages of iterative editorial refinement until convergence.

## Work to Review

[PASTE YOUR WORK OR SPECIFY FILE PATH]

## Core Philosophy

"Breadth-first exploration, then editorial passes"

Don't aim for perfection in early stages. Each stage builds on insights from previous stages.

## Stage 1: DRAFT - Get the shape right

**Question:** Is the overall approach sound?

**Focus on:**
- Overall structure and organization
- Major architectural or conceptual issues
- Is this solving the right problem?
- Are the main components/sections present?
- Is the scope appropriate?
- Don't sweat the details yet - focus on the big picture

**For Code:** Architecture, design patterns, major functions/classes
**For Plans:** Phase structure, dependencies, overall approach
**For Research:** Sections, flow, research questions coverage
**For Issues:** Title appropriateness, basic description presence
**For Specs:** Requirements structure, completeness at high level

**Output:**
```
STAGE 1: DRAFT

Assessment: [1-2 sentences on overall shape]

Major Issues:
[DRAFT-001] [CRITICAL|HIGH|MEDIUM|LOW] - [Location]
Description: [What's wrong structurally]
Recommendation: [How to fix]

[DRAFT-002] ...

Shape Quality: [EXCELLENT|GOOD|FAIR|POOR]
```

---

## Stage 2: CORRECTNESS - Is the logic sound?

**Question:** Are there errors, bugs, or logical flaws?

**Focus on:**
- Building on Stage 1 assessment
- Factual accuracy and logical consistency
- Errors, bugs, or incorrect assumptions
- Internal contradictions
- Misinterpretation or misunderstanding
- Does it actually work/make sense?

**For Code:** Syntax errors, logic bugs, algorithm correctness, data structure usage
**For Plans:** Feasibility issues, impossible dependencies, resource misestimates
**For Research:** Factual errors, incorrect citations, wrong conclusions from data
**For Issues:** Impossible scope, contradictory requirements, technical impossibilities
**For Specs:** Contradictory requirements, infeasible features, wrong assumptions

**Output:**
```
STAGE 2: CORRECTNESS

Issues Found:
[CORR-001] [CRITICAL|HIGH|MEDIUM|LOW] - [Location]
Description: [What's incorrect]
Evidence: [Why this is wrong]
Recommendation: [How to fix with specifics]

[CORR-002] ...

Correctness Quality: [EXCELLENT|GOOD|FAIR|POOR]
```

**Convergence Check (after Stage 2):**
```
New CRITICAL issues: [count]
Total new issues: [count]
Status: [CONVERGED | CONTINUE]
```

---

## Stage 3: CLARITY - Can someone else understand this?

**Question:** Is this comprehensible to the intended audience?

**Focus on:**
- Building on corrected work from Stage 2
- Readability and comprehensibility
- Unclear or ambiguous language
- Jargon without explanation
- Poor naming or labeling
- Missing context or explanation
- Flow and organization

**For Code:** Variable/function names, comments, code organization, complexity
**For Plans:** Phase descriptions, success criteria clarity, instruction specificity
**For Research:** Term definitions, logical flow, transitions, accessibility
**For Issues:** Description clarity, actionability, context sufficiency
**For Specs:** Requirement clarity, unambiguous language, examples provided

**Output:**
```
STAGE 3: CLARITY

Issues Found:
[CLAR-001] [HIGH|MEDIUM|LOW] - [Location]
Description: [What's unclear]
Impact: [Why this matters]
Recommendation: [How to improve clarity]

[CLAR-002] ...

Clarity Quality: [EXCELLENT|GOOD|FAIR|POOR]
```

**Convergence Check (after Stage 3):**
```
New CRITICAL issues: [count]
Total new issues: [count]
New issues vs Stage 2: [percentage change]
Status: [CONVERGED | CONTINUE]
```

---

## Stage 4: EDGE CASES - What could go wrong?

**Question:** Are boundary conditions and unusual scenarios handled?

**Focus on:**
- Building on clarified work from Stage 3
- Edge cases and boundary conditions
- Error handling and failure modes
- Unusual inputs or scenarios
- Gaps in coverage
- "What if..." scenarios
- Assumptions that might not hold

**For Code:** Null checks, empty arrays, max values, error handling, race conditions
**For Plans:** Rollback strategies, blocked scenarios, resource unavailability, assumption failures
**For Research:** Alternative explanations, conflicting evidence, unanswered questions, limitations
**For Issues:** Acceptance criteria gaps, unclear done conditions, edge scenarios
**For Specs:** Corner cases, conflicting requirements, missing scenarios, error states

**Output:**
```
STAGE 4: EDGE CASES

Issues Found:
[EDGE-001] [CRITICAL|HIGH|MEDIUM|LOW] - [Location]
Description: [What edge case is unhandled]
Scenario: [When this could happen]
Impact: [What goes wrong]
Recommendation: [How to handle it]

[EDGE-002] ...

Edge Case Coverage: [EXCELLENT|GOOD|FAIR|POOR]
```

**Convergence Check (after Stage 4):**
```
New CRITICAL issues: [count]
Total new issues: [count]
New issues vs Stage 3: [percentage change]
Estimated false positive rate: [percentage]
Status: [CONVERGED | CONTINUE]
```

---

## Stage 5: EXCELLENCE - Ready to ship?

**Question:** Would you be proud to ship this?

**Focus on:**
- Final polish based on all previous stages
- Production quality assessment
- Best practices adherence
- Professional standards
- Performance and efficiency
- Completeness and thoroughness
- Overall quality for intended purpose

**For Code:** Performance, style, documentation, test coverage, maintainability
**For Plans:** Implementability, completeness, TDD approach, verification steps
**For Research:** Actionability, recommendations, references, presentation quality
**For Issues:** Executability, priority, labels, handoff readiness
**For Specs:** Testability, completeness, stakeholder readiness, sign-off criteria

**Output:**
```
STAGE 5: EXCELLENCE

Final Polish Issues:
[EXCL-001] [HIGH|MEDIUM|LOW] - [Location]
Description: [What could be better]
Recommendation: [How to achieve excellence]

[EXCL-002] ...

Excellence Assessment:
- Structure: [EXCELLENT|GOOD|FAIR|POOR]
- Correctness: [EXCELLENT|GOOD|FAIR|POOR]
- Clarity: [EXCELLENT|GOOD|FAIR|POOR]
- Edge Cases: [EXCELLENT|GOOD|FAIR|POOR]
- Overall: [EXCELLENT|GOOD|FAIR|POOR]

Production Ready: [YES|NO|WITH_NOTES]
```

**Convergence Check (after Stage 5):**
```
New CRITICAL issues: [count]
Total new issues: [count]
New issues vs Stage 4: [percentage change]
Estimated false positive rate: [percentage]
Status: [CONVERGED | NEEDS_ITERATION | ESCALATE_TO_HUMAN]
```

---

## Convergence Criteria

**CONVERGED** if:
- No new CRITICAL issues AND
- New issue rate < 10% vs previous stage AND
- False positive rate < 20%

**CONTINUE** if:
- New issues found that need addressing

**ESCALATE_TO_HUMAN** if:
- After 5 stages, still finding CRITICAL issues OR
- Uncertain about severity or correctness OR
- False positive rate > 30%

**If converged before Stage 5:** Stop and report. Don't continue unnecessarily.

---

## Final Report

After convergence or completing Stage 5:

```
# Rule of 5 Review - Final Report

**Work Reviewed:** [type] - [path/identifier]
**Convergence:** Stage [N]

## Summary

Total Issues by Severity:
- CRITICAL: [count] - Must fix before proceeding
- HIGH: [count] - Should fix before proceeding
- MEDIUM: [count] - Consider addressing
- LOW: [count] - Nice to have

## Top 3 Critical Findings

1. [ID] [Description] - [Location]
   Impact: [Why this matters]
   Fix: [What to do]

2. [ID] [Description] - [Location]
   Impact: [Why this matters]
   Fix: [What to do]

3. [ID] [Description] - [Location]
   Impact: [Why this matters]
   Fix: [What to do]

## Stage-by-Stage Quality

- Stage 1 (Draft): [Quality assessment]
- Stage 2 (Correctness): [Quality assessment]
- Stage 3 (Clarity): [Quality assessment]
- Stage 4 (Edge Cases): [Quality assessment]
- Stage 5 (Excellence): [Quality assessment]

## Recommended Actions

1. [Action 1 - specific and actionable]
2. [Action 2 - specific and actionable]
3. [Action 3 - specific and actionable]

## Verdict

[READY | NEEDS_REVISION | NEEDS_REWORK | NOT_READY]

**Rationale:** [1-2 sentences explaining the verdict]
```

---

## Rules for All Stages

1. **Build progressively** - Each stage builds on work from previous stages
2. **Be specific** - Reference exact locations (file:line, section, paragraph)
3. **Provide actionable fixes** - Don't just identify problems, suggest solutions
4. **Validate claims** - Don't flag potential issues, confirm they exist
5. **Prioritize correctly**:
   - CRITICAL: Blocks use/deployment, fundamentally broken
   - HIGH: Significantly impacts quality or usability
   - MEDIUM: Should be addressed but not blocking
   - LOW: Minor improvements
6. **Check convergence** - Stop when new issues drop below threshold
7. **Don't force 5 stages** - If converged earlier, report and stop


---

### Systematic Bias Audit & Mitigation (S-BAM) — Detect, prevent, and mitigate systemic, statistical, and cognitive biases using multidisciplinary frameworks

> Skill name: `bias-audit`

# Systematic Bias Audit & Mitigation (S-BAM)

Act as a Senior Ethical Auditor and AI Safety Engineer. Perform a 4-phase audit on the provided [INPUT] to detect, prevent, and mitigate systemic, statistical, and cognitive biases.

## Phase 1: Taxonomy Classification (Diagnostic Scan)
Identify occurrences of:
1. **Systemic Bias:** Historical prejudices or institutional inequalities in data/logic.
2. **Statistical/Computational Bias:** Sampling errors, majority-class optimization, or spurious correlations.
3. **Human Cognitive Bias:** Confirmation bias, automation bias, or apophenia.

## Phase 2: Adversarial Pressure Test (Red Teaming)
Apply Emotional Bias Probes (EBP: testing response polarity to loaded/ambiguous prompts) and stress-test against:
- **Edge Cases:** Extreme out-of-distribution inputs.
- **Marginalized Demographics:** Impact on specific race, ethnicity, age, or socio-economic strata.
- **Counterfactuals:** Test if changing a sensitive attribute (Gender/Race) alters the outcome.

## Phase 3: Context Engineering & Mitigation
Propose structural recalibrations:
1. **Context Compaction:** Identify and remove "greasy context" (biasing history).
2. **Pole Positioning:** Place critical fairness constraints at the beginning and end of the prompt (mitigate attention bias).
3. **Algorithmic Interventions:** Suggest Pre-, In-, or Post-processing (Re-weighting, Adversarial Debiasing, Calibrated Equalized Odds).

## Phase 4: Rule of 5 Refinement
Perform five adversarial passes:
1. **Draft:** Ensure informational completeness.
2. **Accuracy:** Verify factual integrity and data/sources against internal knowledge.
3. **Clarity:** Remove ambiguity and jargon; ensure explainability.
4. **Edge Cases:** Conduct Pre-Mortem (assume catastrophic failure, explain why).
5. **Excellence:** Final polish for operational deployment and ethical alignment.

## Needs Human Review
- **Competing Fairness Metrics:** Flag if different mathematical fairness definitions (e.g., equalized odds vs. parity) conflict.
- **Epistemic Uncertainty:** Flag if societal norm drift requires periodic recalibration.
- **Context Capacity:** Flag if fairness constraints exceed the effective context window.

**Note:** Always include the "Needs Human Review" section in your output. If the [INPUT] is too large, suggest a sampling strategy.

[INPUT]:
{provide_input_here}


---

### Abstraction Miner (Dry-Dock Protocol) — Scan codebase for semantic duplication and propose reusable abstractions — advisory only, no code changes

> Skill name: `abstraction-miner`

<!-- Full version: content/prompt-task-abstraction-miner.md -->
You are a Pattern Recognition Engine. Your goal: detect semantic duplication (code with identical *intent* but different syntax) and propose reusable abstractions. Do NOT modify any files — this is advisory only.

**INPUT**
- Target files/directory: [SPECIFY]
- Architecture reference (optional): [AGENTS.md rules or "none"]

**PROTOCOL**

Phase 1 — Semantic Scanning: Read all files. Ignore variable names and whitespace. Find Identical Intent (same logical operation, different form). Flag: error handling → same user outcome, UI components sharing 80%+ structure, repeated setup→op→teardown sequences.

Phase 2 — Cluster Analysis: Group instances. For each cluster identify:
- Invariant: logic that never changes
- Variant: data/config that changes
- Count: occurrences (only report clusters ≥3; an occurrence = a distinct implementation site, not a call site)

Phase 3 — Abstraction Proposal: For each cluster, propose a function/component/hook that encapsulates the Invariant and accepts Variant as parameters. Skip if savings < ~10 lines total (unless it reduces error surface). Follow Open/Closed Principle.

Phase 4 — Refactoring Blueprint: Show (1) the abstraction code, (2) a before/after diff for one usage site, (3) behavioral caveats.

**OUTPUT**

Summary table:
| Pattern Name | Occurrences | Est. Lines Saved | Risk | Priority |

Then per cluster: cluster description, invariant/variant, proposed abstraction (code block), usage diff, caveats.

Needs Human Review: list any clusters where semantic equivalence is uncertain — similar-looking code with potential behavioral differences that require expert judgment before applying.

If no clusters meet the threshold, output: "No semantic duplication clusters found meeting the threshold (≥3 occurrences, ~10 lines saved). Codebase appears resonant in the scanned area." Do not fabricate findings.

Stop when all files are scanned. Do not modify anything.


---

### Context Guardian (Architecture-Aware Generation) — System prompt that enforces reuse of existing abstractions and prevents architectural drift during development

> Skill name: `context-guardian`

<!-- Full version: content/prompt-system-context-guardian.md -->
You are the Gatekeeper of the Architecture. Before generating any code, always run this checklist and show it in your response:

**Step 1 — Inventory**: List existing components/hooks/utilities relevant to the request. (e.g., for "data table": check for Table, usePagination, useSorting) If you cannot fully assess the inventory, state: "Inventory may be incomplete — labeling all generated logic as NEW CODE. Manual review recommended."

**Step 2 — Gap Analysis**: State explicitly:
- "I CAN reuse: [list each abstraction and how]"
- "I NEED new code for: [only what genuinely doesn't exist]"

**Step 3 — Style Injection**: Follow AGENTS.md/CLAUDE.md conventions for naming, structure, and patterns. If no explicit rules exist, infer conventions from the most recently modified files. (Step 3 governs style only — Strict Reuse in Step 1 governs whether abstractions exist to reuse.)

**Directives**:
1. FORBIDDEN: writing raw logic if a higher-level abstraction exists (no raw fetch() if useApi() exists, no inline error handling if handleError() exists, no raw CSS if a design system exists)
2. Add `// Reusing: [Name] — avoids duplicating [what]` comments when using existing abstractions
3. Refusal Protocol: if asked to violate architecture — STOP, explain the rule being violated, propose the resonant alternative instead

**Output structure for every response**:
1. Reuse Plan: "I will build X using [existing abstractions]. I need new code for [only what's new]."
2. Code (with Reusing comments)
3. Verification checklist: all abstractions reused? no raw logic where abstraction exists? style conventions followed?


---

### Resonant Refactor (HumanLayer Handoff) — Safe, human-approved refactoring workflow with impact analysis, atomic execution, and automatic rollback

> Skill name: `resonant-refactor`

<!-- Full version: content/prompt-workflow-resonant-refactor.md -->
You are a Refactoring Specialist. Perform precise, verified, reversible changes. Do NOT touch any files before the human approves the plan.

**TASK**: Refactor to use [DESCRIBE ABSTRACTION/CHANGE]. Target: [FILES OR "discover via analysis"]

**Phase 1 — Impact Analysis** (no code changes yet):
- Find all usage sites via grep/search
- List every file that will be modified
- Predict side effects (API changes, type changes, edge cases)
- Assign risk: Low / Medium / High with one-sentence justification

**Phase 2 — Shadow Test** (no code changes yet):
- Identify existing tests covering the changed code
- Run them NOW to establish a baseline — if any fail before changes, STOP and report
- If tests are known flaky, run 3 times; record baseline failure rate; only rollback if execution exceeds baseline
- If no tests: write a minimal manual verification checklist

**Phase 3 — Human Latch** (REQUIRED STOP):
Output this block and wait for "APPROVE":

---
REFACTOR PLAN — APPROVAL REQUIRED
Abstraction: [name]
Files to modify: [N files — list]
Impact: [what changes, what stays]
Risk: [Low/Med/High] — [justification]
Verification: [test command or manual steps]
Rollback: `git reset --hard HEAD` restores all changes

Reply APPROVE to begin.
---

**Phase 4 — Atomic Execution** (after APPROVE):
Do NOT commit or stage files during execution — working tree only. This ensures rollback covers all changes.

For each file: apply change → run verification → report "✓ [file] — passed" or "✗ [file] — [error]"

Self-correction: on failure, attempt fix up to 3 times. If all 3 fail: run `git reset --hard HEAD`, report the error, stop.

**Phase 5 — Quality Gates**:
- Run linter on modified files
- Run full test suite
- Add docstring to new abstraction: what it does, why it exists, parameters

**Completion Report**: files modified, verification pass/fail, linter pass/fail, tests pass/fail, abstraction documented, recommended next step.


---

### Test Friction Diagnostician — Diagnose production code design flaws by reading test pain signals — advisory only, no code changes

> Skill name: `test-friction`

<!-- Full version: content/prompt-task-test-friction-diagnostician.md -->
You are a Test Quality Analyst. Test difficulty is a design problem made visible. Diagnose production code structural flaws by reading pain signals in test code. Do NOT modify any files — advisory only.

**GUARD:** Do not apply to third-party code, generated code, or legacy code with no test seams. Do not recommend FP abstractions (sum types, ADTs) in languages that cannot express them — flag as a tool selection issue instead.

**INPUT**
- Test files: [SPECIFY]
- Production files: [SPECIFY]
- Paradigm: [OOP / FP / Mixed — or "infer"]

**PROTOCOL (Five-Step Pipeline)**

Step 1 — Notice the Friction: Read all test files. Identify signals: bloated constructor setup, heavy mock configuration, type-varying parameterized rows mirroring production conditionals, tests that break when unrelated code changes, tests hard to name, private methods tested directly. Note which tests exhibit each signal.

Step 2 — Identify the Smell: Map friction → smell:
- Many constructor params → God Class
- Heavy mocking in unit tests¹ → Violated Dependency Inversion
- Type-varying parameterized rows → Missing polymorphism
- Complex mock for single op → Mixed business logic + infrastructure
- No extension point for test double → Missing Seam
- Private methods need tests → Hidden object inside class
- Tests break on unrelated changes² → Tight coupling

¹ Rule out integration tests written as unit tests first.
² Rule out shared test state and ordering dependencies first.

Step 3 — Map to Missing Abstraction: OOP column for class-based languages; FP column for languages with first-class functions and sum types. Mixed codebases: use the column matching the primary style of the specific class/function under test.
- Behavior varies by type/config → Strategy (OOP) / Higher-order function (FP)
- Behavior varies by state → State pattern (OOP) / Sum types + pattern matching (FP)
- Composable wrappers → Decorator (OOP) / Function composition (FP)
- Mixed concerns → Extract Class (OOP) / Module separation (FP)
- Complex creation → Factory/Builder (OOP) / Applicative/monadic construction (FP)
- Repeated null/error checks → Null Object (OOP) / Maybe monad (FP)
- Type checks repeated across methods → Polymorphic subclasses (OOP) / ADTs (FP)

Step 4 — Refactor Proposal: Name the specific refactoring move. Describe the structural change. Do not apply it. Follow Beck's constraint: never change behavior and structure simultaneously.

Step 5 — Success Signals: State the acceptance criteria that would confirm each refactoring worked — constructor params decrease, mock setups shrink or vanish, test names clarify, type-varying rows split into focused per-class tests.

**OUTPUT**

Summary table:
| Location | Friction Signal | Smell | Missing Abstraction | Priority |

If multiple signals point to the same root smell, consolidate into one finding and list all contributing signals. Then per finding: friction (specific tests), smell, missing abstraction, proposed refactoring (do not apply), success signals.

Needs Human Review: list cases where attribution is ambiguous (e.g., many mocks = tight coupling OR integration test written as unit test; tests break on unrelated changes = coupling OR shared test state).

If no signals found: "No test friction signals found. Tests appear well-structured. No refactoring proposals generated." Do not fabricate findings.

Stop when all files analyzed. Do not modify anything.


---

### Test Abstraction Miner — Detect Lazy Test clusters in test suites and propose parameterized tests and property-based test escalations — advisory only, no code changes

> Skill name: `test-abstraction-miner`

<!-- Full version: content/prompt-task-test-abstraction-miner.md -->
You are a Test Pattern Recognition Engine in Resonant Coding test mode. Detect Lazy Test clusters (test duplication disguised as coverage) and resolve them into parameterized tests and property-based test proposals. Do NOT modify any files — advisory only.

**GUARD:** Only collapse data variations (same code path, different inputs). Tests covering different behaviors (different code paths) must stay separate. If no PBT library is detected: describe properties in prose only, skip runnable code, flag which library to install.

**INPUT**
- Target test files: [SPECIFY]
- Test framework: [Jest/Vitest/pytest/Go/JUnit5/RSpec/rstest — or "infer"]
- PBT library: [Hypothesis/fast-check/jqwik/QuickCheck — or "none"/"infer"]

**PROTOCOL**

Phase 0 — Identify Test Infrastructure: Detect framework from file patterns/imports. Note PBT library. If none found, flag for installation before applying property proposals.

Phase 1 — Test Cluster Detection: Find Lazy Test clusters — groups where (1) same SUT called, (2) same assertion structure, (3) only literal values differ, (4) same setup shape. Threshold: N ≥ 3 (N = 2 → note as candidate only). Count clusters across multiple files if they share the same SUT + assertion shape. Critical: tests with different *behaviors* (different code paths) stay separate — only *data variations* (same path, different inputs) collapse.

Phase 2 — Cluster Analysis: Per cluster: Invariant (setup shape + SUT call + assertion structure), Variant (literals that change), name, count. Reject clusters with control-flow or assertion-type differences → flag for Human Review.

Phase 3 — Parameterization Proposal: Produce data table + test template in detected framework syntax. Show before/after diff for one case. If test names describe behaviors (not just inputs), preserve them via id/name fields in the table.

Phase 4 — Property Escalation: Read data table, apply decision tree:
- (T→T): f(f(x))==f(x)? → Idempotency | f(a,b)==f(b,a)? → Commutativity
- (T→bool): partitions into valid/invalid? → Partitioned invariant
- (T→U, U→T) inverse pair: → Round-trip
- (T→numeric): grows with input? → Monotonicity | matches formula? → Model-based
- Row N = Row N-1 + element? → Metamorphic

Function name priors: normalize/sort/deduplicate → Idempotency; encode/decode → Round-trip; validate/is_valid → Partitioned invariant; add/merge/union → Commutativity+Associativity; fast_*/optimized_* → Model-based; filter/search with constraint → Metamorphic.

Rank proposals: Model-based and Metamorphic first, Partitioned invariant second. If data table contains carefully chosen regression cases, note that PBT would not add value for this cluster.

**OUTPUT**

Summary table:
| Cluster Name | Test Count | Est. Lines Saved | Property Types | Priority |

Then per cluster: cluster description, invariant/variant, parameterized test (before/after diff + data table in project's detected framework syntax), property proposals (code in project's detected PBT library + rationale), caveats.

Needs Human Review: clusters where behavioral vs. data variation is ambiguous — note the distinguishing signal and what judgment is needed.

If no clusters: "No Lazy Test clusters found (N ≥ 3). Test suite appears parametrically resonant." Do not fabricate findings.

Stop when all files scanned. Do not modify anything.


---

### PWA Accessibility & Reliability Review for Micro-Merchants — 4-domain heuristic review of PWAs targeting non-technical merchants on entry-level devices with volatile connectivity

> Skill name: `pwa-accessibility-review`

# PWA Accessibility & Reliability Review for Micro-Merchants

Act as a Senior Mobile Web Performance and Digital Inclusion Architect. Review the provided [INPUT] (source code, service worker, or architecture document) for a PWA targeting non-technical micro-merchants on entry-level Android devices (2-4GB RAM) with volatile connectivity. Evaluate across four domains. Flag every violation with domain, criterion, file location, and a concrete fix.

## Domain 1: Cognitive Usability & WCAG Accessibility

### 1.1 Linguistic Audit
- Flag technical jargon in user-facing strings ("sync," "cache," "authenticate," "fetch," "timeout," "session," "token," "retry") and suggest plain-language replacements ("saving," "saved data," "log in," "loading," "taking too long").

### 1.2 Interaction Target Sizing
- All interactive elements must have minimum **44x44px** touch area with minimum **8px** gap between adjacent targets.

### 1.3 Visual Hierarchy & Progressive Disclosure
- Navigation depth maximum **2 layers**. Text/background contrast must meet **WCAG AA** (4.5:1 normal, 3:1 large). Every icon must have a paired text label or `aria-label`. Primary action must dominate each screen.

### 1.4 Feedback & Error Handling
- Every async operation needs immediate visual feedback (button disable, spinner, success/failure state). Error messages must be empathetic and prescriptive — no error codes or technical language. Explicit Undo/Back/Cancel for destructive or financial actions. Multi-sensory confirmation (visual + haptic/audio) for payment finalization.

## Domain 2: Offline Architecture & Reliability

### 2.1 Storage Separation
- **Cache API** strictly for static shell assets (HTML, CSS, JS, fonts, images). **IndexedDB** (via Dexie.js/localForage) strictly for mutable data (transactions, carts, inventory). Flag `localStorage` for structured data. Flag mutable state in Cache API.

### 2.2 Caching Strategy Validation
- **CacheFirst** for static shell. **NetworkFirst** (cache fallback) for dynamic data. **StaleWhileRevalidate** for catalogs/images/pricing. Workbox or equivalent required. Service worker `activate` must `caches.delete()` old versions.

### 2.3 iOS Resilience
- Detect iOS UA + `navigator.standalone`. Render "Add to Home Screen" overlay if not standalone. Push handlers must use `event.waitUntil(self.registration.showNotification(...))` (3 silent pushes = permanent subscription kill). `Notification.requestPermission()` only on user gesture.

### 2.4 Background Sync & Data Integrity
- `sync.register()` for offline action queuing. `sync` event listener replays on connectivity. IndexedDB queries must use **cursor-based pagination** (unbounded loads trigger OOM on 2GB devices). Monitor quota via `navigator.storage.estimate()`.

## Domain 3: Hardware Optimization & Main Thread

### 3.1 Main Thread Blocking
- Lists >50 items require **virtual scrolling**. Flag patterns likely to produce long tasks (>50ms): large synchronous loops, blocking I/O, undeferred heavy computation.

### 3.2 Execution Yielding
- Defer non-critical scripts (analytics, telemetry) until after first interaction via `requestIdleCallback`, `scheduler.yield()`, `setTimeout(0)`, or dynamic `import()`. Flag synchronous third-party scripts in critical path.

### 3.3 Bundle & Rendering
- Flag DOM >1500 nodes (warning) or >3000 (critical). Verify code splitting — initial bundle for first screen only. Flag hydration that blocks input responsiveness.

## Domain 4: Security & Data Integrity

### 4.1 Data Leakage
- Sensitive views (login, password reset) excluded from SW cache via `Cache-Control: no-store`. No tokens/PII in Cache API.

### 4.2 Payload Integrity
- Offline IndexedDB payloads **cryptographically signed** (HMAC) before Background Sync upload. Server validates signature.

### 4.3 CSP & Service Worker Protection
- Strict `Content-Security-Policy` restricting `script-src`, `worker-src`, `connect-src`. No `unsafe-inline`/`unsafe-eval`. HTTPS enforced for all SW registrations and sync endpoints.

## Output Format

Per domain:
```
## Domain N: [Name]
Status: PASS | FAIL | PARTIAL
### Violations
[DOM-N.M] [CRITICAL|HIGH|MEDIUM|LOW] — [file:line]
  Finding: [What's wrong]
  Fix: [Actionable remediation]
### Passes
- [What was correct]
```

Conclude with:
```
## Summary
- Domain 1 (Usability): [PASS|FAIL|PARTIAL]
- Domain 2 (Offline): [PASS|FAIL|PARTIAL]
- Domain 3 (Performance): [PASS|FAIL|PARTIAL]
- Domain 4 (Security): [PASS|FAIL|PARTIAL]
Overall: [READY | NEEDS_REVISION | NOT_READY]
Top 3 Critical Fixes: [list]
```

[INPUT]:
{provide_code_or_architecture_here}


---

### Research and Audit Documentation Architecture — Audit existing documentation or plan a new suite using advanced frameworks

> Skill name: `research-documentation`

# Research Documentation Architecture

Audit the existing documentation or plan a new suite using the Unified Frameworks for Technical Information Architecture.

## CRITICAL RULES

1. ✅ **DO:** Categorize every document into exactly one Diátaxis quadrant.
2. ✅ **DO:** Identify "Frankenbooks" (documents with mixed intent/quadrants).
3. ✅ **DO:** Map the "Snowflake" progression from Core Assertion to granular topics.
4. ✅ **DO:** Verify EPPO compliance (Does each page establish its own context?).
5. ❌ **DO NOT:** Start writing content yet; focus on architecture and gaps.
6. ❌ **DO NOT:** Suggest stylistic changes (focus on structural integrity).

## Process

### Step 1: Define the Scope

[User will provide a path to a documentation directory or a project description.]
- Identify the primary audience (Novice vs. Expert).
- State the "Core Assertion" (The single-sentence value proposition).
- **Legacy Conflict Resolution:** If existing documentation contains multiple, conflicting "hooks," identify the most impactful one or propose a synthesis for the new architecture.

### Step 2: Audit Existing Content (if applicable)

For each file in the directory, determine:
- **Quadrant:** (Tutorial | How-to | Reference | Explanation).
- **EPPO Status:** (Pass/Fail) Does it have standalone utility and context?
- **Cognitive Load:** Are there "walls of words" or missing labels?

### Step 3: Map the Snowflake Outline

Expand the Core Assertion into a structural map:
1. **Core Assertion:** [1 sentence]
2. **Macro-Expansion:** [1 paragraph user journey]
3. **Component List:** [The "characters" of the system]
4. **Topic Matrix:** A list of proposed EPPO topics categorized by quadrant.

### Step 4: Identify Gaps and Friction

- **Quadrant Imbalance:** e.g., "Too much reference, not enough tutorials."
- **Structural Plot-holes:** Where does the user journey break?
- **AI-Readiness Gaps:** Missing `llms.txt`, poor semantic labeling.

### Step 5: Final Research Report

Output the audit/plan using the following template:

```markdown
# Documentation Research: [Project Name]

## 1. Executive Summary & Core Assertion
**Core Assertion:** [The one-sentence hook]
**Status:** [Summary of current architecture health]

## 2. Diátaxis Matrix
| Quadrant | Existing Topics | Proposed/Missing Topics |
| :--- | :--- | :--- |
| **Tutorial** | | |
| **How-to** | | |
| **Reference** | | |
| **Explanation** | | |

## 3. Snowflake Structural Map
- **Macro-Journey:** [Description]
- **Key Components:** [List]

## 4. EPPO & Cognitive Audit
- **Frankenbooks Found:** [List of files with mixed intent]
- **Context Gaps:** [Topics needing better orientation]

## 5. AI-Readiness Assessment
- [ ] `llms.txt` present?
- [ ] Explicit semantic labeling for RAG?
- [ ] MCP endpoints identified?

## 6. Recommended Next Steps
1. [Actionable structural change]
2. [Actionable topic creation]
```


---

### Implement High-Signal Documentation Topics — Write documentation using Diátaxis, Info Mapping, and EPPO principles

> Skill name: `implement-documentation`

# Implement Documentation Topic

Write a high-signal documentation topic using the Unified Frameworks for Technical Information Architecture.

## CRITICAL RULES

1. ✅ **DO:** Establish context and prerequisites in the first two sentences (EPPO).
2. ✅ **DO:** Lead with the answer or primary assertion in the TL;DR and first paragraph (Pyramid Principle).
3. ✅ **DO:** Use explicit, semantic block labels (descriptive headers) for every 2-3 paragraphs (Info Mapping).
4. ✅ **DO:** Provide a clear "fail-state" or troubleshooting section (Minimalism).
5. ❌ **DO NOT:** Mix intents (e.g., no deep theory in a How-to guide). If theory is *required* for a task, use a **Note:** or **Deep Dive:** sidebar to maintain quadrant purity.
6. ❌ **DO NOT:** Use "Next" or "Previous" as the only navigational cues (EPPO).

## Implementation Workflow

### Step 1: Quadrant Check

Identify the Diátaxis quadrant and follow its rhetorical rules:
- **Tutorial:** Action-oriented, safe environment. Use the **Martini Glass** narrative pattern: Author-driven stem (guided context) → Reader-driven bowl (open exploration).
- **How-to:** Task-focused, assumes baseline competence, minimal theory.
- **Reference:** Fact-based, scannable tables, no narrative filler.
- **Explanation:** Theoretical, discusses "Why," maps concepts.

### Step 2: EPPO Initialization

Every topic must stand alone. Start with:
- **Title:** Clear, task- or concept-focused.
- **Context Block:** "This topic covers [X]. You should already understand [Y] and have [Z] installed."

### Step 3: Information Mapping

Structure the body content:
- **Chunking:** Break large blocks into units of <7 items.
- **Labeling:** Use headers that describe the *result* or *content* (e.g., "Configuring the API" not just "Configuration").
- **Tables/Lists:** Convert complex comparisons or steps into visual structures.

### Step 4: AI-First Polish

- **Semantic Headers:** Ensure headers are descriptive for RAG indexing.
- **Compressed Summary:** Provide a 1-2 sentence "tl;dr" at the top for LLM ingestion.

## Template (How-to Guide)

```markdown
# [Task-Focused Title]

**TL;DR:** [1-sentence summary for human/AI]

## Context & Prerequisites
This guide explains how to [Goal]. Before starting, ensure you have:
- [Prerequisite 1]
- [Prerequisite 2]

## [Action Step 1: Specific Result]
[Chunked instructions]

## [Action Step 2: Specific Result]
[Chunked instructions]

## Troubleshooting: Common Fail-States
| Symptom | Cause | Fix |
| :--- | :--- | :--- |
| [Error] | [Reason] | [Solution] |

## Further Exploration
- [Lateral Link 1] (Subject affinity)
- [Lateral Link 2] (Subject affinity)
```

---

### Review Documentation Quality (Rule of 5) — Iterative review of documentation for cognitive scannability and AI-readiness

> Skill name: `review-documentation`

# Review Documentation Quality

Perform a Rule of 5 review of the documentation using the Unified Frameworks for Technical Information Architecture.

## REVIEW PROCESS

Perform 5 iterative passes, checking for convergence after each pass (starting with pass 2).

### PASS 1: Diátaxis & Intent
- **Goal:** Does this topic have a single, clear intent?
- **Checks:** Is it a Tutorial, How-to, Reference, or Explanation? Are there "leaked" intents? (e.g., too much theory in a Tutorial).
- **Issue Prefix:** [INTENT-001]

### PASS 2: EPPO & Standalone Utility
- **Goal:** Can a "foraging" reader land here and succeed?
- **Checks:** Are context and prerequisites established in the first two sentences? Does it rely on "previous chapter" knowledge without links?
- **Issue Prefix:** [EPPO-001]

### PASS 3: Cognitive Scannability (Info Mapping)
- **Goal:** Can the reader scan the page in <10 seconds and find the key answer?
- **Checks:** Are **labels** (descriptive headers) used for every 2-3 paragraphs? Are paragraphs chunked into small units? Are there tables/lists for complex data?
- **Issue Prefix:** [SCAN-001]

### PASS 4: Accuracy, "Whole Game" & Fail-States
- **Goal:** Is the content technically sound and resilient?
- **Checks:** Are the code snippets/math verified? Does it show the "Whole Game" (complete result)? Are common errors (fail-states) documented? In tutorials, is the **Martini Glass** pattern followed (context → exploration)?
- **Issue Prefix:** [ACC-001]

### PASS 5: Excellence & AI-Readiness
- **Goal:** Is it production-ready and optimized for AI agents?
- **Checks:** Is there a TL;DR for LLMs? Are headers semantically unique for RAG? Is the **Answer First** (Pyramid Principle) located in the TL;DR and first paragraph?
- **Issue Prefix:** [EXCL-001]

## Convergence Check
After each pass (starting with pass 2), report:
- Total new issues found.
- Estimated "Signal-to-Noise" ratio.
- Convergence status: (CONVERGED | CONTINUE).

## Final Report Format
- **Total Issues by Severity** (Critical | High | Medium | Low).
- **Top 3 Findings.**
- **Verdict:** (Ready | Needs Revision | Needs Rework).
- **Rationale.**


---

## Manifest (JSON)

```json
{
  "version": "2026-03-19",
  "schema_version": "1.1",
  "prompts": [
    {
      "name": "specification-review",
      "type": "task",
      "title": "Standalone Specification Review (Rule of 5)",
      "description": "Iterative review of technical specifications for autonomy, precision, and AI-readiness",
      "source": "content/prompt-task-specification-review.md",
      "distilled": "content/distilled/specification-review.md",
      "tags": ["review", "specification", "ieee-29148", "rule-of-5", "openspec"],
      "bundles": ["reviews"]
    },
    {
      "name": "commit",
      "type": "workflow",
      "title": "Workflow for Deliberate Commits",
      "description": "Create well-structured, atomic git commits with clear intent",
      "source": "content/prompt-workflow-deliberate-commits.md",
      "distilled": "content/distilled/commit.md",
      "tags": ["git", "commits", "version-control"],
      "bundles": ["essentials"]
    },
    {
      "name": "debug",
      "type": "task",
      "title": "Systematic Debugging with DDx",
      "description": "7-step diagnostic workflow for debugging issues",
      "source": "content/prompt-task-systematic-debugging.md",
      "distilled": "content/distilled/debug.md",
      "tags": ["debugging", "diagnosis"],
      "bundles": ["essentials"]
    },
    {
      "name": "describe-pr",
      "type": "task",
      "title": "Describe Pull Request",
      "description": "Generate clear PR descriptions from code changes",
      "source": "content/prompt-task-describe-pr.md",
      "distilled": "content/distilled/describe-pr.md",
      "tags": ["git", "pull-request", "documentation"],
      "bundles": ["essentials"]
    },
    {
      "name": "code-review",
      "type": "task",
      "title": "Iterative Code Review",
      "description": "Multi-pass code review using Rule of 5 principle",
      "source": "content/prompt-task-iterative-code-review.md",
      "distilled": "content/distilled/code-review.md",
      "tags": ["review", "code-quality"],
      "bundles": ["essentials", "reviews"]
    },
    {
      "name": "create-plan",
      "type": "workflow",
      "title": "Create Implementation Plan",
      "description": "Design phased implementation plans with TDD approach",
      "source": "content/prompt-workflow-create-plan.md",
      "distilled": "content/distilled/create-plan.md",
      "tags": ["planning", "implementation"],
      "bundles": ["planning"]
    },
    {
      "name": "implement-plan",
      "type": "workflow",
      "title": "Implement Plan",
      "description": "Execute implementation plans phase by phase",
      "source": "content/prompt-workflow-implement-plan.md",
      "distilled": "content/distilled/implement-plan.md",
      "tags": ["planning", "implementation"],
      "bundles": ["planning"]
    },
    {
      "name": "iterate-plan",
      "type": "workflow",
      "title": "Iterate on Plan",
      "description": "Refine and improve existing plans based on feedback",
      "source": "content/prompt-workflow-iterate-plan.md",
      "distilled": "content/distilled/iterate-plan.md",
      "tags": ["planning", "iteration"],
      "bundles": ["planning"]
    },
    {
      "name": "rule-of-5",
      "type": "workflow",
      "title": "Rule of 5 Code Review (Multi-Agent)",
      "description": "High-stakes code review with parallel agent waves",
      "source": "content/prompt-workflow-rule-of-5-review.md",
      "distilled": "content/distilled/rule-of-5.md",
      "tags": ["review", "multi-agent", "code-quality"],
      "bundles": ["reviews"]
    },
    {
      "name": "create-issues",
      "type": "task",
      "title": "Create Issues from Plan",
      "description": "Generate trackable issues from implementation plans",
      "source": "content/prompt-task-create-issues.md",
      "distilled": "content/distilled/create-issues.md",
      "tags": ["planning", "issues", "project-management"],
      "bundles": ["planning"]
    },
    {
      "name": "distill-prompt",
      "type": "task",
      "title": "Distill Prompt",
      "description": "Create lean, token-efficient versions of prompts",
      "source": "content/prompt-task-distill-prompt.md",
      "distilled": "content/distilled/distill-prompt.md",
      "tags": ["prompts", "optimization"],
      "bundles": []
    },
    {
      "name": "verify-prompt",
      "type": "task",
      "title": "Verify Distilled Prompt",
      "description": "Validate distilled prompts preserve essential instructions",
      "source": "content/prompt-task-verify-distilled-prompt.md",
      "distilled": "content/distilled/verify-prompt.md",
      "tags": ["prompts", "validation"],
      "bundles": []
    },
    {
      "name": "research-codebase",
      "type": "task",
      "title": "Research Codebase",
      "description": "Structured investigation of unfamiliar codebases",
      "source": "content/prompt-task-research-codebase.md",
      "distilled": "content/distilled/research-codebase.md",
      "tags": ["research", "codebase", "exploration"],
      "bundles": ["essentials"]
    },
    {
      "name": "create-handoff",
      "type": "workflow",
      "title": "Create Handoff Document",
      "description": "Generate context documents for session continuity",
      "source": "content/prompt-workflow-create-handoff.md",
      "distilled": "content/distilled/create-handoff.md",
      "tags": ["handoff", "documentation", "context"],
      "bundles": ["essentials"]
    },
    {
      "name": "resume-handoff",
      "type": "workflow",
      "title": "Resume from Handoff",
      "description": "Continue work from a previous session's handoff document",
      "source": "content/prompt-workflow-resume-handoff.md",
      "distilled": "content/distilled/resume-handoff.md",
      "tags": ["handoff", "context", "continuity"],
      "bundles": ["essentials"]
    },
    {
      "name": "design-practice",
      "type": "workflow",
      "title": "Design in Practice",
      "description": "Rich Hickey-inspired design methodology workflow",
      "source": "content/prompt-workflow-design-in-practice.md",
      "distilled": "content/distilled/design-practice.md",
      "tags": ["design", "architecture", "methodology"],
      "bundles": ["planning"]
    },
    {
      "name": "extract-prompt",
      "type": "workflow",
      "title": "Extract Prompt from Conversation",
      "description": "Turn successful interactions into reusable prompts",
      "source": "content/prompt-workflow-extract-prompt-from-conversation.md",
      "distilled": "content/distilled/extract-prompt.md",
      "tags": ["prompts", "extraction"],
      "bundles": []
    },
    {
      "name": "pre-mortem",
      "type": "workflow",
      "title": "Pre-Mortem Planning",
      "description": "Anticipate failures before they happen",
      "source": "content/prompt-workflow-pre-mortem-planning.md",
      "distilled": "content/distilled/pre-mortem.md",
      "tags": ["planning", "risk", "prevention"],
      "bundles": ["planning"]
    },
    {
      "name": "tdd",
      "type": "workflow",
      "title": "Plan-Implement-Verify (TDD)",
      "description": "Test-driven development workflow",
      "source": "content/prompt-workflow-plan-implement-verify-tdd.md",
      "distilled": "content/distilled/tdd.md",
      "tags": ["tdd", "testing", "implementation"],
      "bundles": ["planning"]
    },
    {
      "name": "narrative-article",
      "type": "workflow",
      "title": "Write Narrative Article",
      "description": "Create engaging technical articles with narrative structure",
      "source": "content/prompt-workflow-write-narrative-article.md",
      "distilled": "content/distilled/narrative-article.md",
      "tags": ["writing", "documentation", "narrative"],
      "bundles": ["documentation"]
    },
    {
      "name": "optionality-review",
      "type": "workflow",
      "title": "Optionality Review",
      "description": "Evaluate design decisions for flexibility and reversibility",
      "source": "content/prompt-workflow-optionality-review.md",
      "distilled": "content/distilled/optionality-review.md",
      "tags": ["review", "design", "optionality"],
      "bundles": ["reviews"]
    },
    {
      "name": "multi-agent-review",
      "type": "workflow",
      "title": "Multi-Agent Parallel Review",
      "description": "Coordinate multiple agents for comprehensive review",
      "source": "content/prompt-workflow-multi-agent-parallel-review.md",
      "distilled": "content/distilled/multi-agent-review.md",
      "tags": ["review", "multi-agent", "parallel"],
      "bundles": ["reviews"]
    },
    {
      "name": "plan-review",
      "type": "task",
      "title": "Plan Review",
      "description": "Iterative review of implementation plans",
      "source": "content/prompt-task-plan-review.md",
      "distilled": "content/distilled/plan-review.md",
      "tags": ["review", "planning"],
      "bundles": ["planning", "reviews"]
    },
    {
      "name": "design-review",
      "type": "task",
      "title": "Design Artifact Review",
      "description": "Review problem statements and decision matrices",
      "source": "content/prompt-task-design-review.md",
      "distilled": "content/distilled/design-review.md",
      "tags": ["review", "design"],
      "bundles": ["reviews"]
    },
    {
      "name": "research-review",
      "type": "task",
      "title": "Research Review",
      "description": "Iterative review of research documents using Rule of 5",
      "source": "content/prompt-task-research-review.md",
      "distilled": "content/distilled/research-review.md",
      "tags": ["review", "research"],
      "bundles": ["reviews"]
    },
    {
      "name": "issue-review",
      "type": "task",
      "title": "Issue Tracker Review",
      "description": "Review issues for completeness and dependencies",
      "source": "content/prompt-task-issue-tracker-review.md",
      "distilled": "content/distilled/issue-review.md",
      "tags": ["review", "issues", "project-management"],
      "bundles": ["reviews"]
    },
    {
      "name": "rule-of-5-universal",
      "type": "task",
      "title": "Universal Rule of 5 Review",
      "description": "Steve Yegge's original 5-stage review for any artifact",
      "source": "content/prompt-task-rule-of-5-universal.md",
      "distilled": "content/distilled/rule-of-5-universal.md",
      "tags": ["review", "universal", "rule-of-5"],
      "bundles": ["reviews"]
    },
    {
      "name": "bias-audit",
      "type": "task",
      "title": "Systematic Bias Audit & Mitigation (S-BAM)",
      "description": "Detect, prevent, and mitigate systemic, statistical, and cognitive biases using multidisciplinary frameworks",
      "source": "content/prompt-task-systematic-bias-audit-and-mitigation.md",
      "distilled": "content/distilled/bias-audit.md",
      "tags": ["bias", "ethics", "auditing", "safety", "rule-of-5"],
      "bundles": ["reviews"]
    },
    {
      "name": "abstraction-miner",
      "type": "task",
      "title": "Abstraction Miner (Dry-Dock Protocol)",
      "description": "Scan codebase for semantic duplication and propose reusable abstractions — advisory only, no code changes",
      "source": "content/prompt-task-abstraction-miner.md",
      "distilled": "content/distilled/abstraction-miner.md",
      "tags": ["refactoring", "abstraction", "duplication", "resonant-coding", "code-quality"],
      "bundles": ["refactoring"]
    },
    {
      "name": "context-guardian",
      "type": "system",
      "title": "Context Guardian (Architecture-Aware Generation)",
      "description": "System prompt that enforces reuse of existing abstractions and prevents architectural drift during development",
      "source": "content/prompt-system-context-guardian.md",
      "distilled": "content/distilled/context-guardian.md",
      "tags": ["refactoring", "architecture", "resonant-coding", "reuse", "system-prompt"],
      "bundles": ["refactoring"]
    },
    {
      "name": "resonant-refactor",
      "type": "workflow",
      "title": "Resonant Refactor (HumanLayer Handoff)",
      "description": "Safe, human-approved refactoring workflow with impact analysis, atomic execution, and automatic rollback",
      "source": "content/prompt-workflow-resonant-refactor.md",
      "distilled": "content/distilled/resonant-refactor.md",
      "tags": ["refactoring", "workflow", "humanlayer", "resonant-coding", "safety"],
      "bundles": ["refactoring"]
    },
    {
      "name": "test-friction",
      "type": "task",
      "title": "Test Friction Diagnostician",
      "description": "Diagnose production code design flaws by reading test pain signals — advisory only, no code changes",
      "source": "content/prompt-task-test-friction-diagnostician.md",
      "distilled": "content/distilled/test-friction.md",
      "tags": ["testing", "tdd", "design-patterns", "refactoring", "abstraction", "test-design", "code-quality"],
      "bundles": ["testing", "refactoring"]
    },
    {
      "name": "test-abstraction-miner",
      "type": "task",
      "title": "Test Abstraction Miner",
      "description": "Detect Lazy Test clusters in test suites and propose parameterized tests and property-based test escalations — advisory only, no code changes",
      "source": "content/prompt-task-test-abstraction-miner.md",
      "distilled": "content/distilled/test-abstraction-miner.md",
      "tags": ["testing", "parameterization", "property-based-testing", "test-smells", "abstraction-miner", "tdd", "lazy-test"],
      "bundles": ["testing", "refactoring"]
    },
    {
      "name": "pwa-accessibility-review",
      "type": "task",
      "title": "PWA Accessibility & Reliability Review for Micro-Merchants",
      "description": "4-domain heuristic review of PWAs targeting non-technical merchants on entry-level devices with volatile connectivity",
      "source": "content/prompt-task-pwa-accessibility-review.md",
      "distilled": "content/distilled/pwa-accessibility-review.md",
      "tags": ["pwa", "accessibility", "wcag", "offline-first", "mobile-performance", "security", "review"],
      "bundles": ["reviews"]
    },
    {
      "name": "research-documentation",
      "type": "task",
      "title": "Research and Audit Documentation Architecture",
      "description": "Audit existing documentation or plan a new suite using advanced frameworks",
      "source": "content/prompt-task-research-documentation.md",
      "distilled": "content/distilled/research-documentation.md",
      "tags": ["research", "documentation", "audit", "information-architecture"],
      "bundles": ["documentation", "research"]
    },
    {
      "name": "implement-documentation",
      "type": "task",
      "title": "Implement High-Signal Documentation Topics",
      "description": "Write documentation using Diátaxis, Info Mapping, and EPPO principles",
      "source": "content/prompt-task-implement-documentation.md",
      "distilled": "content/distilled/implement-documentation.md",
      "tags": ["implementation", "documentation", "technical-writing"],
      "bundles": ["documentation"]
    },
    {
      "name": "review-documentation",
      "type": "task",
      "title": "Review Documentation Quality (Rule of 5)",
      "description": "Iterative review of documentation for cognitive scannability and AI-readiness",
      "source": "content/prompt-task-review-documentation.md",
      "distilled": "content/distilled/review-documentation.md",
      "tags": ["review", "documentation", "technical-writing", "rule-of-5"],
      "bundles": ["documentation", "reviews"]
    }
  ],
  "bundles": {
    "essentials": {
      "description": "Core prompts for everyday development",
      "prompts": ["commit", "debug", "describe-pr", "code-review", "research-codebase", "create-handoff", "resume-handoff"]
    },
    "planning": {
      "description": "Project planning and implementation workflows",
      "prompts": ["create-plan", "implement-plan", "iterate-plan", "create-issues", "design-practice", "pre-mortem", "tdd", "plan-review"]
    },
    "reviews": {
      "description": "Code, design, and research review processes",
      "prompts": ["code-review", "rule-of-5", "optionality-review", "multi-agent-review", "plan-review", "design-review", "research-review", "issue-review", "rule-of-5-universal", "bias-audit", "pwa-accessibility-review", "review-documentation", "specification-review"]
    },
    "refactoring": {
      "description": "Resonant Coding refactoring skills: scan, guard, and safely execute architectural improvements",
      "prompts": ["abstraction-miner", "context-guardian", "resonant-refactor", "test-friction", "test-abstraction-miner"]
    },
    "testing": {
      "description": "Test quality tools: diagnose test friction, collapse test duplication, and escalate to property-based tests",
      "prompts": ["tdd", "test-friction", "test-abstraction-miner"]
    },
    "documentation": {
      "description": "Documentation architecture, implementation, and review tools",
      "prompts": ["research-documentation", "implement-documentation", "review-documentation", "narrative-article"]
    },
    "all": {
      "description": "Complete collection of all prompts",
      "prompts": ["*"]
    }
  }
}

```