---
name: brainstorming
description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
---

# Brainstorming Ideas Into Designs

Turn ideas into designs through collaborative dialogue, BEFORE any code. Pairs with Brian's `14-independent-idea-engine` and the SUPREME "brainstorm-first" rule.

<HARD-GATE>
No implementation skill, code, scaffold, or implementation action until a design is presented AND the user approves it. EVERY project, regardless of perceived simplicity.
</HARD-GATE>

## "Too simple to need a design" is the trap

"Simple" projects (todo list, one-function util, config change) hide the most unexamined assumptions. Design can be a few sentences — but present it and get approval.

## Checklist (one task each, in order)

1. **Explore project context** — files, docs, recent commits. Follow existing patterns.
2. **Offer the visual companion just-in-time** — NOT upfront. Offer (own message) the first time a question is genuinely clearer shown than told; never if no visual question arises. See `visual-companion.md`.
3. **Ask clarifying questions** — one per message, multiple-choice preferred. Purpose / constraints / success criteria.
4. **Propose 2-3 approaches** — trade-offs, lead with your recommendation + why.
5. **Present design** — sections scaled to complexity (sentences → 200-300 words). Approval after each. Cover architecture, components, data flow, error handling, testing.
6. **Write design doc** — `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` (user pref overrides path), commit.
7. **Spec self-review** — inline scan: placeholders/TBD, contradictions, ambiguity, scope. Fix and move on; no re-review.
8. **User reviews written spec** — ask, wait. Changes → fix + re-review. Proceed only on approval.
9. **Transition** — invoke `writing-plans`. This is the ONLY skill you invoke next — never frontend-design, mcp-builder, or any other implementation skill.

## Scope before refining

- If the request spans multiple independent subsystems (chat + storage + billing + analytics), flag it BEFORE refining details.
- Too large for one spec → decompose into sub-projects (pieces, relations, build order); brainstorm the first through the normal flow. Each sub-project gets its own spec → plan → implement cycle.

## Design for isolation

- Split into units with one clear purpose, well-defined interfaces, independently testable. For each: what it does, how to use it, what it depends on.
- Can someone understand a unit without reading internals? Can you change internals without breaking consumers? If not, boundaries need work. A file growing large signals it does too much.

## Working in existing code

- Explore structure first; follow existing patterns.
- Fold in targeted improvements where existing problems affect the work (oversized file, tangled responsibilities) — like a good dev improving code they touch. No unrelated refactoring.

## Principles

- One question at a time; multiple-choice preferred.
- YAGNI ruthlessly. Always explore 2-3 approaches. Validate incrementally. Go back and clarify when something doesn't fit.

## Visual Companion (summary)

A browser tool, not a mode — available for visual questions, doesn't route every question through the browser.

- **Offer just-in-time, as its own message** — no other content. Wait for response. Accept → start server with `--open`. Decline → text-only, don't re-offer.
- **Decide per question:** would the user understand this better seen than read? Browser for mockups / wireframes / layout comparisons / diagrams; terminal for requirements / concepts / tradeoffs / scope. A UI *topic* is not automatically a visual question.
- On accept, read `visual-companion.md` before proceeding.

<!-- budget: ~56 -->

# Spec Document Reviewer Prompt Template

Dispatch a subagent to verify a spec is complete, consistent, and ready for planning. Use after the spec is written to `docs/superpowers/specs/`.

```
Subagent (general-purpose):
  description: "Review spec document"
  prompt: |
    You are a spec document reviewer. Verify this spec is complete and ready for planning.

    **Spec to review:** [SPEC_FILE_PATH]

    ## What to Check

    | Category | What to Look For |
    |----------|------------------|
    | Completeness | TODOs, placeholders, "TBD", incomplete sections |
    | Consistency | Internal contradictions, conflicting requirements |
    | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
    | Scope | Focused enough for a single plan — not covering multiple independent subsystems |
    | YAGNI | Unrequested features, over-engineering |

    ## Calibration

    **Only flag issues that would cause real problems during implementation planning.**
    A missing section, a contradiction, or a requirement so ambiguous it could be
    interpreted two different ways — those are issues. Minor wording improvements,
    stylistic preferences, and "sections less detailed than others" are not.

    Approve unless there are serious gaps that would lead to a flawed plan.

    ## Output Format

    ## Spec Review

    **Status:** Approved | Issues Found

    **Issues (if any):**
    - [Section X]: [specific issue] - [why it matters for planning]

    **Recommendations (advisory, do not block approval):**
    - [suggestions for improvement]
```

**Reviewer returns:** Status, Issues (if any), Recommendations

# Visual Companion Guide

Optional browser server for showing mockups, diagrams, and side-by-side options during brainstorming. Implementation lives in `scripts/` (server.cjs, helper.js, frame-template.html) — this guide covers what's non-obvious.

## When to use (per-question, not per-session)

Test: **would the user understand this better seen than read?**

- **Browser** — content that IS visual: UI mockups/wireframes, architecture diagrams, side-by-side layout/color comparisons, look-and-feel/spacing, state machines as diagrams.
- **Terminal** — content that is text: requirements/scope, conceptual A/B/C choices, tradeoff lists, API/data-model decisions, anything answered in words.

A question *about* a UI topic isn't automatically visual. "What kind of wizard?" → terminal. "Which wizard layout?" → browser.

## Start / stop

```bash
scripts/start-server.sh --project-dir /path/to/project --open   # start AFTER user approves
scripts/stop-server.sh $SESSION_DIR                              # stop
```

- Returns JSON with `port`, `url` (carries a `?key=…`), `screen_dir`, `state_dir` — save these. Also written to `$STATE_DIR/server-info` if you backgrounded it without capturing stdout.
- `--project-dir` persists mockups under `.superpowers/brainstorm/` and enables same-port restart; without it files go to `/tmp` and are cleaned on stop. Remind the user to gitignore `.superpowers/`.
- `--open` auto-opens the browser; still share the full `url` as fallback (headless/remote won't auto-open).

### Non-obvious gotchas

- **Always hand out the COMPLETE `url` including `?key=…`** — the server rejects keyless HTTP/WebSocket requests (gates stray tabs / other machines). After first load a cookie remembers it, so reloads and `/files/*` work without the query string.
- **Platform backgrounding** — Claude Code default works (script self-backgrounds). Windows/Codex auto-switch to foreground; Gemini/Copilot need `--foreground` + the platform's background-exec flag so the server survives across turns.
- **Remote/containerized unreachable URL** — bind non-loopback: `--host 0.0.0.0 --url-host localhost`.
- Server auto-exits after 4h idle (`--idle-timeout-minutes`).

## The loop

1. **Confirm server alive** before referring to the URL — `$STATE_DIR/server-info` exists, `$STATE_DIR/server-stopped` does not. If down, restart with the SAME `--project-dir` (reuses port; the user's tab reconnects from its "paused" overlay — no new URL needed).
2. **Write a fresh HTML file** to `screen_dir` — semantic name (`layout.html`), never reuse a filename, iterations get `-v2`. Use your file tool, never cat/heredoc. Server serves the newest by mtime.
3. **End your turn**: remind URL every step, one-line summary of what's on screen, ask them to respond in terminal (clicks optional).
4. **Next turn**: read `$STATE_DIR/events` (JSONL of clicks; cleared on each new screen; absent = no interaction) and merge with their terminal text — terminal is primary.
5. **Unload when leaving the browser** — push a `waiting.html` ("Continuing in terminal…") so they don't stare at a resolved choice.

## Writing content

- **Write content fragments, not full documents.** Anything not starting with `<!DOCTYPE`/`<html>` is auto-wrapped in the frame template (header, theme CSS, connection status, interactivity). Full docs only when you need total control.
- Markup the frame provides — selectable options/cards (`onclick="toggleSelect(this)"`, `data-choice`, `data-multiselect`), `.mockup` / `.split` / `.cards`, `.pros-cons`, mock wireframe elements (`.mock-nav`/`.mock-sidebar`/`.mock-content`/`.mock-button`/`.mock-input`/`.placeholder`), typography (`h2`/`h3`/`.subtitle`/`.section`/`.label`). Full reference: `scripts/frame-template.html`.

## Design tips

- 2-4 options max per screen; scale fidelity to the question (wireframe for layout, polish for polish).
- State the question on every page ("Which feels more professional?" not "Pick one").
- Real content where it matters (real Unsplash images for a photo portfolio) — placeholders hide design issues.

---
name: finishing-a-development-branch
description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
---

# Finishing a Development Branch

Integrate finished work: verify → detect environment → choose integration → execute → clean up.

Under `[[no-staging-doctrine]]` + `[[main-only-branch]]` the default is **merge to `main` + auto-push** — diffs clearing all gates auto-merge. Don't offer "keep the branch as-is, handle it later"; finish the work this turn. PR only when a human review is explicitly wanted.

Announce: "Using the finishing-a-development-branch skill to complete this work."

## Step 1 — gate before integrating

- Run the project test suite. Failures block — show them, fix first, do NOT integrate broken code.
- Full deploy + prod-E2E gate is `[[verification-loop]]` — local green ≠ done.

## Step 2 — detect environment

```bash
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
```

- `GIT_DIR == GIT_COMMON` → normal repo, no worktree cleanup.
- `GIT_DIR != GIT_COMMON`, named branch → worktree, provenance-based cleanup (Step 4).
- Detached HEAD → externally managed; no local-merge, no cleanup (push-as-branch or discard only).
- Base branch: `git merge-base HEAD main || git merge-base HEAD master`, or confirm with the user.

## Step 3 — integrate

- **Merge to base (default).** `cd` to main repo root first (CWD safety), merge, re-run tests on the merged result, then Step 4 cleanup, then `git branch -d`. Always auto-push the merged base.

  ```bash
  MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel); cd "$MAIN_ROOT"
  git checkout <base> && git pull && git merge <feature> && <test cmd> && git push
  ```

- **PR (review wanted).** `git push -u origin <feature>`. Do NOT clean up the worktree — it's needed to iterate on feedback.
- **Discard (abandon).** Require a typed `discard` confirmation listing branch + commits + worktree path. Then `cd` to main root, Step 4 cleanup, `git branch -D <feature>`.

## Step 4 — cleanup (merge + discard only; PR preserves the worktree)

```bash
WORKTREE_PATH=$(git rev-parse --show-toplevel)
```

- Normal repo (`GIT_DIR == GIT_COMMON`) → nothing to remove.
- Worktree under `.worktrees/` or `worktrees/` → we own it. From main root (never from inside the worktree): `git worktree remove "$WORKTREE_PATH" && git worktree prune`.
- Anywhere else → harness-owned; use its exit tool (`ExitWorktree`) or leave in place. Never remove a worktree you didn't create.

## Ordering invariants (why the sequence is fixed)

- Merge BEFORE removing the worktree — `git branch -d` fails while a worktree references the branch.
- `cd` to main root BEFORE `git worktree remove` — fails silently when CWD is inside the target.
- `git worktree prune` after removal self-heals stale registrations.

## See

- `[[no-staging-doctrine]]` · `[[main-only-branch]]` · `[[verification-loop]]`
- `using-git-worktrees` — the isolation setup this finishes

<!-- budget: ~62 -->

---
name: receiving-code-review
description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
---

# Receiving Code Review

Feedback is suggestions to evaluate, not orders to follow. **Verify before implementing, ask before assuming** — technical correctness over social comfort. Verify against the codebase the same way `[[verification-loop]]` gates deploys: evidence before action.

## Response pattern

1. Read the full feedback without reacting.
2. Restate each item in your own words — or ask if unclear.
3. Verify against codebase reality; evaluate if it's sound for THIS stack.
4. Acknowledge technically, or push back with reasoning.
5. Implement one item at a time, testing each.

## No performative agreement

- Never "You're absolutely right!" / "Great point!" / "Thanks for catching that!" — any gratitude or praise.
- Never "Let me implement that" before verifying.
- Instead: restate the requirement, ask, push back, or just start working. The code shows you heard it.
- Catch yourself typing "Thanks" or "You're right" → delete it, state the fix.

## Unclear feedback → stop

- If ANY item is unclear, implement NOTHING yet — items may be related; partial understanding ships the wrong fix.
- Ask only about the unclear ones: "Understand 1,2,3,6. Need clarification on 4 and 5 before proceeding."

## Source-specific

- **From your partner** — trusted; implement after understanding, ask if scope unclear, skip to action.
- **From external reviewers** — skeptical but careful. Before implementing, check: correct for THIS codebase? breaks existing behavior? reason the current code exists? works on all target platforms/versions? does the reviewer have full context?
- Can't verify → say so: "Can't verify without [X]. Investigate, ask, or proceed?"
- Conflicts with a prior architectural decision → stop and discuss with your partner first.

## YAGNI check

- Reviewer says "implement it properly" → grep for real usage first.
- Unused → "Nothing calls this endpoint. Remove it (YAGNI)?" Used → implement properly.

## Implementation order

1. Clarify everything unclear first.
2. Then: blocking (breaks/security) → simple (typos/imports) → complex (refactor/logic).
3. Test each fix individually; verify no regressions.

## Push back when

- Suggestion breaks existing functionality, violates YAGNI, is wrong for this stack, ignores legacy/compat reasons, lacks full context, or conflicts with a partner architectural call.
- How: technical reasoning not defensiveness; cite working tests/code; ask specific questions; escalate to partner if architectural.
- Uncomfortable pushing back? Name the tension and raise the issue anyway — honesty is the value.

## Acknowledging

- Correct feedback → "Fixed. [what changed]" or "Good catch — [issue]. Fixed in [location]." No thanks.
- You pushed back and were wrong → "You were right — checked [X], it does [Y]. Fixing." No apology, no over-explaining.

## GitHub threads

Reply inline in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.

**Verify. Question. Then implement.**

## Rationalizations — stop, these are wrong

| Excuse | Reality |
|---|---|
| "Reviewer is more senior" | Senior reviewers make mistakes. Verify technically. |
| "I'll just apply it and move on" | Blind agreement ships bugs the reviewer didn't catch. |
| "The feedback is obviously right" | Obvious things are often wrong. Open the code. |
| "Pushing back is rude" | Shipping bad code is rude. Push back with evidence. |

**Red Flags — STOP and re-read the code yourself:** agreeing without opening a file · "they probably checked" · gratitude instead of verification · applying feedback you don't understand.

<!-- budget: ~63 -->

# Code Reviewer Prompt Template

Fill and paste into a `code-reviewer` (or `general-purpose`) subagent. Reviews completed work against requirements + quality before it cascades.

Placeholders: `[DESCRIPTION]` (what was built) · `[PLAN_OR_REQUIREMENTS]` (plan path/task/requirements) · `[BASE_SHA]` · `[HEAD_SHA]`.

```
You are a Senior Code Reviewer. Review the work below against its plan and
flag issues before they cascade.

## What Was Implemented
[DESCRIPTION]

## Requirements / Plan
[PLAN_OR_REQUIREMENTS]

## Git Range
git diff --stat [BASE_SHA]..[HEAD_SHA]
git diff [BASE_SHA]..[HEAD_SHA]

## Read-Only
Inspect with git show/diff/log only. Never mutate the working tree, index,
HEAD, or branch. Need another revision? git worktree add /tmp/review-[SHA] [SHA].

## Check
- Plan alignment — all planned functionality present; deviations justified, not drift.
- Code quality — separation of concerns, error handling, type safety, edge cases, DRY without premature abstraction.
- Architecture — sound design, scalability/perf, security, clean integration.
- Testing — real behavior not mocks, edge + integration coverage, all passing.
- Production — migration strategy on schema change, backward compat, docs, no obvious bugs.

## Calibration
Categorize by ACTUAL severity — not everything is Critical. Acknowledge what's
done well first (accurate praise earns trust). Flag plan deviations specifically
so the implementer can confirm intent. If the plan itself is wrong, say so.

## Output

### Strengths
[Specific, what's well done]

### Issues
#### Critical (Must Fix)
[Bugs, security, data loss, broken functionality]
#### Important (Should Fix)
[Architecture, missing features, weak error handling, test gaps]
#### Minor (Nice to Have)
[Style, optimization, doc polish]

Per issue: file:line · what's wrong · why it matters · how to fix (if not obvious).

### Recommendations
[Code/architecture/process improvements]

### Assessment
**Ready to merge?** [Yes | No | With fixes]
**Reasoning:** [1-2 sentence technical verdict]

## Rules
DO: categorize by real severity · cite file:line · explain WHY · name strengths · give a clear verdict.
DON'T: say "looks good" unchecked · mark nitpicks Critical · review code you didn't read · be vague · dodge the verdict.
```

## Example output (what good looks like)

```
### Strengths — clean schema with proper migrations (db.ts:15-42); 18 tests covering fallbacks (summarizer.ts:85-92)
### Issues
#### Important
1. Missing --help in CLI wrapper (index-conversations:1-31) — no --concurrency discovery. Fix: add --help with usage.
2. No date validation (search.ts:25-27) — invalid dates silently return nothing. Fix: validate ISO, throw with example.
#### Minor — no "X of Y" progress on long ops (indexer.ts:130)
### Assessment — Ready to merge: With fixes. Solid core, good tests; help + validation are quick and don't touch core.
```

---
name: requesting-code-review
description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
---

# Requesting Code Review

Dispatch a reviewer subagent on completed work. Feed it crafted context (description + requirements + git range) — never your session history. Keeps the reviewer on the work product and preserves your own context.

**Review early, review often.**

Brian's stack already ships a purpose-built `code-reviewer` agent + the **Agent Diversity Review gate** (`[[agent-selection]]`). Prefer the named agent over a bare `general-purpose` spawn; this skill is the request protocol that complements both.

## When to request

Mandatory:

1. Before merge to main
2. After each task in subagent-driven development
3. After completing a major feature

Optional: when stuck (fresh eyes), before a refactor (baseline), after a complex bugfix.

## How to request

1. Get SHAs — `BASE_SHA=$(git rev-parse origin/main)`, `HEAD_SHA=$(git rev-parse HEAD)`.
2. Spawn the `code-reviewer` agent (or `general-purpose` filling [code-reviewer.md](code-reviewer.md)).
3. Fill placeholders: `{DESCRIPTION}` (what you built), `{PLAN_OR_REQUIREMENTS}` (what it should do), `{BASE_SHA}`, `{HEAD_SHA}`.

## Act on feedback

1. Fix Critical immediately; fix Important before proceeding.
2. Note Minor for later.
3. Push back with technical reasoning if the reviewer is wrong — see `[[receiving-code-review]]`.

## Never

- Skip review because "it's simple".
- Ignore Critical, or proceed with unfixed Important.
- Argue with valid technical feedback.

<!-- budget: ~40 -->

# Implementer Subagent Prompt Template

Dispatch template for an implementer subagent.

```
Subagent (general-purpose):
  description: "Implement Task N: [task name]"
  model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
         model silently inherits the session's most expensive one]
  prompt: |
    You are implementing Task N: [task name]

    ## Task Description

    Read your task brief first: [BRIEF_FILE]
    It contains the full task text from the plan.

    ## Context

    [Scene-setting: where this fits, dependencies, architectural context]

    ## Before You Begin

    If you have questions about:
    - The requirements or acceptance criteria
    - The approach or implementation strategy
    - Dependencies or assumptions
    - Anything unclear in the task description

    **Ask them now.** Raise any concerns before starting work.

    ## Your Job

    Once you're clear on requirements:
    1. Implement exactly what the task specifies
    2. Write tests (following TDD if task says to)
    3. Verify implementation works
    4. Commit your work
    5. Self-review (see below)
    6. Report back

    Work from: [directory]

    **While you work:** If you encounter something unexpected or unclear, **ask questions**.
    It's always OK to pause and clarify. Don't guess or make assumptions.

    While iterating, run the focused test for what you're changing; run the
    full suite once before committing, not after every edit.

    ## Code Organization

    Your edits are more reliable when files are focused. Keep this in mind:
    - Follow the file structure defined in the plan
    - Each file should have one clear responsibility with a well-defined interface
    - If a file you're creating is growing beyond the plan's intent, stop and report
      it as DONE_WITH_CONCERNS — don't split files on your own without plan guidance
    - If an existing file you're modifying is already large or tangled, work carefully
      and note it as a concern in your report
    - In existing codebases, follow established patterns. Improve code you're touching
      the way a good developer would, but don't restructure things outside your task.

    ## When You're in Over Your Head

    It is always OK to stop and say "this is too hard for me." Bad work is worse than
    no work. You will not be penalized for escalating.

    **STOP and escalate when:**
    - The task requires architectural decisions with multiple valid approaches
    - You need to understand code beyond what was provided and can't find clarity
    - You feel uncertain about whether your approach is correct
    - The task involves restructuring existing code in ways the plan didn't anticipate
    - You've been reading file after file trying to understand the system without progress

    **How to escalate:** Report back with status BLOCKED or NEEDS_CONTEXT. Describe
    specifically what you're stuck on, what you've tried, and what kind of help you need.
    The controller can provide more context, re-dispatch with a more capable model,
    or break the task into smaller pieces.

    ## Before Reporting Back: Self-Review

    Review your work with fresh eyes. Ask yourself:

    **Completeness:**
    - Did I fully implement everything in the spec?
    - Did I miss any requirements?
    - Are there edge cases I didn't handle?

    **Quality:**
    - Is this my best work?
    - Are names clear and accurate (match what things do, not how they work)?
    - Is the code clean and maintainable?

    **Discipline:**
    - Did I avoid overbuilding (YAGNI)?
    - Did I only build what was requested?
    - Did I follow existing patterns in the codebase?

    **Testing:**
    - Do tests actually verify behavior (not just mock behavior)?
    - Did I follow TDD if required?
    - Are tests comprehensive?
    - Is the test output pristine (no stray warnings or noise)?

    If you find issues during self-review, fix them now before reporting.

    ## After Review Findings

    If a reviewer finds issues and you fix them, re-run the tests that cover
    the amended code and append the results to your report file. Reviewers
    will not re-run tests for you — your report is the test evidence.

    ## Report Format

    Write your full report to [REPORT_FILE]:
    - What you implemented (or what you attempted, if blocked)
    - What you tested and test results
    - **TDD Evidence** (if TDD was required for this task):
      - RED: command run, relevant failing output before implementation, and why the failure was expected
      - GREEN: command run and relevant passing output after implementation
    - Files changed
    - Self-review findings (if any)
    - Any issues or concerns

    Then report back with ONLY (under 15 lines — the detail lives in the
    report file):
    - **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
    - Commits created (short SHA + subject)
    - One-line test summary (e.g. "14/14 passing, output pristine")
    - Your concerns, if any
    - The report file path

    If BLOCKED or NEEDS_CONTEXT, put the specifics in the final message
    itself — the controller acts on it directly.

    Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
    Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need
    information that wasn't provided. Never silently produce work you're unsure about.
```

---
name: subagent-driven-development
description: Use when executing implementation plans with independent tasks in the current session
---

# Subagent-Driven Development

Execute a plan in ONE session: dispatch a fresh implementer subagent per task → task review (spec + quality) after each → broad whole-branch review at the end. Upstream: <https://github.com/obra/superpowers>.

Fresh-context briefs, fan-out width, and the per-task economy are governed by `[[parallel-subagent-economy]]`; when to decompose-and-fan-out at all by `[[monitor-orchestration]]`. This file covers only what is SDD-specific: the per-task implementer + two-stage review loop.

## Contents

1. When to use vs. alternatives
2. The per-task loop
3. Model selection
4. Handling implementer status
5. Constructing reviewer prompts
6. File handoffs + durable ledger
7. Red flags

## When to Use

- Have a plan + tasks mostly independent + staying in THIS session → this skill.
- Want a parallel session with human checkpoints → `superpowers:executing-plans` instead.
- Tightly-coupled tasks or no plan → brainstorm/manual first.
- Continuous execution: do not check in between tasks. Stop only on unresolvable BLOCKED, genuine ambiguity, or all-done. Narrate ≤1 line between tool calls — the ledger and tool results are the record.

## The Per-Task Loop

1. Read plan once; note global constraints; create todos + check the ledger (§6).
2. Pre-flight: scan the plan for tasks that contradict each other/the constraints, or that mandate something the rubric treats as a defect (test asserting nothing, verbatim-duplicated logic). Batch all findings to the human as one question before Task 1; if clean, proceed silently.
3. Per task: `scripts/task-brief PLAN N` → dispatch implementer (`implementer-prompt.md`). Answer its questions before it proceeds.
4. On DONE: `scripts/review-package BASE HEAD` → dispatch task reviewer (`task-reviewer-prompt.md`) with the printed path.
5. Reviewer returns two verdicts (spec + quality). Critical/Important findings → fix subagent → re-review. Loop until both clean.
6. Mark complete in todos + ledger. Next task.
7. After all tasks: final whole-branch review via `../requesting-code-review/code-reviewer.md`, then `superpowers:finishing-a-development-branch`.

## Model Selection

Least-powerful model that handles the role. Always specify model explicitly — an omitted model inherits the session's (most expensive) model and defeats this.

- Plan text contains the complete code → transcription → cheapest tier.
- Single-file mechanical fix, complete spec → cheap.
- Multi-file integration / pattern-matching / debugging → standard (mid-tier is the floor for reviewers and prose-spec implementers).
- Design judgment / broad codebase understanding → most capable. The final whole-branch review is always this tier.
- Reviewer model scales to the diff's size/risk, not the session default.
- Turn count beats token price: cheapest models take 2-3× the turns on multi-step work, costing more overall.

## Handling Implementer Status

- **DONE** → generate review package, dispatch reviewer.
- **DONE_WITH_CONCERNS** → read concerns first. Correctness/scope → resolve before review; observations → note and proceed.
- **NEEDS_CONTEXT** → provide the missing info, re-dispatch.
- **BLOCKED** → diagnose: context gap → re-dispatch same model with more context; needs reasoning → more capable model; too large → split; plan is wrong → escalate to human. Never retry the same model unchanged; never ignore an escalation.

**Reviewer ⚠️ "cannot verify from diff" items** — requirements in unchanged code or spanning tasks. Non-blocking for the rest of the review, but YOU resolve each before marking complete (you hold the cross-task context the reviewer lacks). A confirmed gap = failed spec review → back to implementer.

## Constructing Reviewer Prompts

Per-task reviews are task-scoped gates; the broad review runs once at the end.

1. **Never pre-judge.** No "do not flag X", "at most Minor", "the plan chose this". If you're tempted to spare yourself a loop, stop — let the reviewer raise it and adjudicate in the loop. The plan's example code is a starting point, not proof its weaknesses were chosen.
2. **BASE is the commit recorded before dispatching the implementer — never `HEAD~1`** (drops all but the last commit of a multi-commit task).
3. Global-constraints block = the reviewer's attention lens. Copy binding requirements verbatim from the plan: exact values, formats, stated relationships ("same layout as X"). Process rules (YAGNI, test hygiene) are already in the template.
4. No open-ended directives ("check all uses", "run race tests if useful") without a concrete task-specific reason. Don't ask it to re-run tests the implementer already ran on the same code.
5. **Plan-mandated findings** (or any finding conflicting with plan text) → the human decides: present finding + plan text, ask which governs. Don't dismiss it; don't dispatch a contradicting fix without asking.
6. Fix dispatches carry the implementer contract: re-run the covering tests (name them — a one-line fix doesn't need the full suite), report command + output. Confirm all three present before re-review.
7. Critical/Important → fix subagents. Minor → ledger, fed to the final review for triage. Final-review findings → ONE fix subagent with the full list, not one fixer per finding (each rebuilds context + re-runs suites).
8. Final review gets its own package: `scripts/review-package $(git merge-base main HEAD) HEAD`.

## File Handoffs + Durable Ledger

Everything pasted into a dispatch — and everything a subagent prints back — stays resident in your context and is re-read every later turn. Move artifacts as files.

- **Brief** — `scripts/task-brief PLAN N` extracts the task to a file. Dispatch = (1) one line on where the task fits; (2) brief path ("read first — your requirements, exact values verbatim"); (3) interfaces/decisions from earlier tasks the brief can't know; (4) your resolution of any ambiguity you spotted; (5) report-file path + contract. Exact values live ONLY in the brief.
- **Report** — name it after the brief (`task-N-brief.md` → `task-N-report.md`). Implementer writes full detail there, returns only status + commits + one-line test summary + concerns.
- **Reviewer** gets three paths — brief, report, review-package — plus the binding global constraints.
- Never paste accumulated prior-task summaries into later dispatches (a real session hit 42k chars, 99% pasted history). A fresh subagent needs its task, the interfaces it touches, the constraints. Nothing else.

**Ledger** — conversation memory dies at compaction; controllers have re-dispatched entire completed sequences (most expensive failure observed). Track in `$(git rev-parse --show-toplevel)/.superpowers/sdd/progress.md`:

- At start, `cat` it — tasks marked complete are DONE, resume at the first unmarked one.
- On a clean review, append (same message as other bookkeeping): `Task N: complete (commits <base7>..<head7>, review clean)`.
- After compaction, trust the ledger + `git log` over recollection. `git clean -fdx` destroys it (git-ignored scratch) → recover from `git log`.

## Red Flags — Never

- Implement on main/master without explicit consent.
- Skip task review, or accept a report missing either verdict (spec AND quality both required).
- Dispatch multiple implementers in parallel (conflicts).
- Make a subagent read the whole plan (hand it the brief).
- Dispatch a task reviewer without a diff file — generate it first.
- Move to the next task with open Critical/Important findings, or accept "close enough" on spec.
- Let implementer self-review replace actual review (both needed).
- Re-dispatch a task the ledger already marks complete.

## Prompt Templates + Integration

- `implementer-prompt.md` · `task-reviewer-prompt.md` · final review: `../requesting-code-review/code-reviewer.md`.
- Workflow skills: `superpowers:using-git-worktrees` (isolated workspace), `superpowers:writing-plans` (creates the plan), `superpowers:finishing-a-development-branch` (completion). Subagents follow `superpowers:test-driven-development` per task.

## Rationalizations — stop, these skip review

| Excuse | Reality |
|---|---|
| "One more task, then review" | Stacked unreviewed tasks compound bugs. Review each before next. |
| "Reviewer flagged it Minor" | Minor findings cascade. Fix or ledger-feed, don't ignore. |
| "Close enough on spec" | "Close enough" is a gap. Let the reviewer adjudicate. |

**Red Flags — STOP:** skipping task review · accepting a report missing either verdict · moving to next task with open Critical/Important · "just this once" · re-dispatching unchanged.

<!-- budget: ~101 -->

# Task Reviewer Prompt Template

Dispatch template for a task reviewer subagent. The reviewer reads the task's
diff once and returns two verdicts: spec compliance and code quality.

**Purpose:** Verify one task's implementation matches its requirements (nothing
more, nothing less) and is well-built (clean, tested, maintainable)

```
Subagent (general-purpose):
  description: "Review Task N (spec + quality)"
  model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
         model silently inherits the session's most expensive one]
  prompt: |
    You are reviewing one task's implementation: first whether it matches its
    requirements, then whether it is well-built. This is a task-scoped gate,
    not a merge review — a broad whole-branch review happens separately after
    all tasks are complete.

    ## What Was Requested

    Read the task brief: [BRIEF_FILE]

    Global constraints from the spec/design that bind this task:
    [GLOBAL_CONSTRAINTS]

    ## What the Implementer Claims They Built

    Read the implementer's report: [REPORT_FILE]

    ## Diff Under Review

    **Base:** [BASE_SHA]
    **Head:** [HEAD_SHA]
    **Diff file:** [DIFF_FILE]

    Read the diff file once — it contains the commit list, a stat summary,
    and the full diff with surrounding context, and it is your view of the
    change. The diff's context lines ARE the changed files: do not Read a
    changed file separately unless a hunk you must judge is cut off
    mid-function — and say so in your report. Do not re-run git commands.
    If the diff file is missing, fetch the diff yourself:
    `git diff --stat [BASE_SHA]..[HEAD_SHA]` and `git diff [BASE_SHA]..[HEAD_SHA]`.
    Do not crawl the broader codebase. Inspect code outside the diff only
    to evaluate a concrete risk you can name — one focused check per named
    risk, and name both the risk and what you checked in your report.
    Cross-cutting changes are legitimate named risks: if the diff changes
    lock ordering, a function or API contract, or shared mutable state,
    checking the call sites is the right method.

    Your review is read-only on this checkout. Do not mutate the working
    tree, the index, HEAD, or branch state in any way.

    ## Do Not Trust the Report

    Treat the implementer's report as unverified claims about the code. It
    may be incomplete, inaccurate, or optimistic. Verify the claims against
    the diff. Design rationales in the report are claims too: "left it per
    YAGNI," "kept it simple deliberately," or any other justification is the
    implementer grading their own work. Judge the code on its merits — a
    stated rationale never downgrades a finding's severity.

    ## Tests

    The implementer already ran the tests and reported results with TDD
    evidence for exactly this code. Do not re-run the suite to confirm their
    report. Run a test only when reading the code raises a specific doubt
    that no existing run answers — and then a focused test, never a
    package-wide suite, race detector run, or repeated/high-count loop. If
    heavy validation seems warranted, recommend it in your report instead of
    running it. If you cannot run commands in this environment, name the
    test you would run.

    Warnings or other noise in the implementer's reported test output are
    findings — test output should be pristine.

    ## Part 1: Spec Compliance

    Compare the diff against What Was Requested:

    - **Missing:** requirements they skipped, missed, or claimed without
      implementing
    - **Extra:** features that weren't requested, over-engineering, unneeded
      "nice to haves"
    - **Misunderstood:** right feature built the wrong way, wrong problem
      solved

    If a requirement cannot be verified from this diff alone (it lives in
    unchanged code or spans tasks), report it as a ⚠️ item instead of
    broadening your search.

    ## Part 2: Code Quality

    **Code quality:**
    - Clean separation of concerns?
    - Proper error handling?
    - DRY without premature abstraction?
    - Edge cases handled?

    **Tests:**
    - Do the new and changed tests verify real behavior, not mocks?
    - Are the task's edge cases covered?

    **Structure:**
    - Does each file have one clear responsibility with a well-defined interface?
    - Are units decomposed so they can be understood and tested independently?
    - Is the implementation following the file structure from the plan?
    - Did this change create new files that are already large, or
      significantly grow existing files? (Don't flag pre-existing file
      sizes — focus on what this change contributed.)

    Your report should point at evidence: file:line references for every
    finding and for any check you would otherwise answer with a bare
    "yes." A tight report that cites lines gives the controller everything
    it needs.

    Your final message is the report itself: begin directly with the
    spec-compliance verdict. Every line is a verdict, a finding with
    file:line, or a check you ran — no preamble, no process narration,
    no closing summary.

    ## Calibration

    Categorize issues by actual severity. Not everything is Critical.
    Important means this task cannot be trusted until it is fixed: incorrect
    or fragile behavior, a missed requirement, or maintainability damage you
    would block a merge over — verbatim duplication of a logic block,
    swallowed errors, tests that assert nothing. "Coverage could be broader"
    and polish suggestions are Minor.
    If the plan or brief explicitly mandates something this rubric calls a
    defect (a test that asserts nothing, verbatim duplication of a logic
    block), that IS a finding — report it as Important, labeled
    plan-mandated. The plan's authorship does not grade its own work; the
    human decides.
    Acknowledge what was done well before listing issues — accurate praise
    helps the implementer trust the rest of the feedback.

    ## Output Format

    ### Spec Compliance

    - ✅ Spec compliant | ❌ Issues found: [what's missing/extra/misunderstood,
      with file:line references]
    - ⚠️ Cannot verify from diff: [requirements you could not verify from the
      diff alone, and what the controller should check — report alongside the
      ✅/❌ verdict for everything you could verify]

    ### Strengths
    [What's well done? Be specific.]

    ### Issues

    #### Critical (Must Fix)
    #### Important (Should Fix)
    #### Minor (Nice to Have)

    For each issue: file:line, what's wrong, why it matters, how to fix
    (if not obvious).

    ### Assessment

    **Task quality:** [Approved | Needs fixes]

    **Reasoning:** [1-2 sentence technical assessment]
```

**Placeholders:**

- `[MODEL]` — REQUIRED: reviewer model per SKILL.md Model Selection
- `[BRIEF_FILE]` — REQUIRED: the task brief file (`scripts/task-brief PLAN N`
  prints the path; same file the implementer worked from)
- `[GLOBAL_CONSTRAINTS]` — the binding requirements copied verbatim from
  the plan's Global Constraints section or the spec: exact values, formats,
  and stated relationships between components (not process rules — those
  are already in this template)
- `[REPORT_FILE]` — REQUIRED: the file the implementer wrote its detailed
  report to
- `[BASE_SHA]` — commit before this task
- `[HEAD_SHA]` — current commit
- `[DIFF_FILE]` — REQUIRED: the path the controller wrote the review
  package to (`scripts/review-package BASE HEAD` prints the unique path it
  wrote; the package never enters the controller's context)

**Reviewer returns:** Spec Compliance verdict (✅/❌/⚠️), Strengths, Issues
(Critical/Important/Minor), Task quality verdict

A fix dispatch can address spec gaps and quality findings together;
re-review after fixes covers both verdicts.

---
name: using-git-worktrees
description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
---

# Using Git Worktrees

Ensure work runs in an isolated workspace. Detect existing isolation first, then prefer the harness's native worktree tool, then fall back to `git worktree`. Never fight the harness.

Pairs with `[[main-only-branch]]` — `main` always committed, worktrees for isolation. The harness ships native worktree tools (`EnterWorktree`/`ExitWorktree`); use them over raw git.

Announce: "Using the using-git-worktrees skill to set up an isolated workspace."

## Step 0 — detect existing isolation

```bash
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)
```

- `GIT_DIR != GIT_COMMON` is ALSO true in a submodule. Guard: `git rev-parse --show-superproject-working-tree` returns a path → you're in a submodule, treat as a normal repo.
- `GIT_DIR != GIT_COMMON` (not submodule) → already in a linked worktree. Skip to Step 2; do NOT nest another. Report the path + branch (note if detached HEAD — branch creation deferred to finish time).
- `GIT_DIR == GIT_COMMON` → normal checkout. If no worktree preference is declared in instructions, ask consent before creating one; honor a declared preference silently; if declined, work in place → Step 2.

## Step 1 — create the workspace

1. **Native `EnterWorktree` tool (the default)** — call it first, always. It owns placement, branch, and cleanup; passing `name` creates, passing `path` switches into an existing one. On exit, `ExitWorktree` with `action: "remove"` or `"keep"`. Never mix with raw `git worktree add` — that creates phantom state the native tool can't see.
2. **Git fallback (only if no native tool):**
   - Directory priority: declared instruction preference > existing `.worktrees/` (wins over `worktrees/`) > default `.worktrees/`.
   - Verify ignored before creating: `git check-ignore -q .worktrees`. If not ignored, add to `.gitignore` + commit first — else worktree contents get tracked.
   - `git worktree add "$LOCATION/$BRANCH_NAME" -b "$BRANCH_NAME" && cd "$_"`.
   - Permission/sandbox denial on add → tell the user, work in place, run setup + baseline there.

## Step 2 — setup + baseline

- Auto-detect and install: `package.json`→`npm install`, `Cargo.toml`→`cargo build`, `requirements.txt`→`pip install -r`, `pyproject.toml`→`poetry install`, `go.mod`→`go mod download`.
- Run the project test suite to confirm a clean baseline. Tests fail → report + ask before proceeding (can't tell new bugs from pre-existing). Tests pass → report ready: path, test count, feature.

## See

- `[[main-only-branch]]` — worktrees for isolation, main always committed
- `finishing-a-development-branch` — merge/PR/cleanup when work is done

<!-- budget: ~43 -->

# Plan Document Reviewer Prompt Template

Dispatch after the complete plan is written — verifies completeness, spec match, and task decomposition.

```
Subagent (general-purpose):
  description: "Review plan document"
  prompt: |
    You are a plan document reviewer. Verify this plan is complete and ready for implementation.

    **Plan to review:** [PLAN_FILE_PATH]
    **Spec for reference:** [SPEC_FILE_PATH]

    ## What to Check

    | Category | What to Look For |
    |----------|------------------|
    | Completeness | TODOs, placeholders, incomplete tasks, missing steps |
    | Spec Alignment | Plan covers spec requirements, no major scope creep |
    | Task Decomposition | Tasks have clear boundaries, steps are actionable |
    | Buildability | Could an engineer follow this plan without getting stuck? |

    ## Calibration

    **Only flag issues that would cause real problems during implementation.**
    An implementer building the wrong thing or getting stuck is an issue.
    Minor wording, stylistic preferences, and "nice to have" suggestions are not.

    Approve unless there are serious gaps — missing requirements from the spec,
    contradictory steps, placeholder content, or tasks so vague they can't be acted on.

    ## Output Format

    ## Plan Review

    **Status:** Approved | Issues Found

    **Issues (if any):**
    - [Task X, Step Y]: [specific issue] - [why it matters for implementation]

    **Recommendations (advisory, do not block approval):**
    - [suggestions for improvement]
```

**Reviewer returns:** Status, Issues (if any), Recommendations

---
name: writing-plans
description: Use when you have a spec or requirements for a multi-step task, before touching code
---

# Writing Plans

Write an implementation plan for an engineer with zero context for this codebase and questionable test taste. Decompose into bite-sized, independently verifiable tasks. DRY, YAGNI, TDD, frequent commits.

Pairs with `/generate-prp` (research-driven blueprint) and `/writing-plans`. Save to `docs/superpowers/plans/YYYY-MM-DD-<feature>.md` (user preference overrides). Worktree, if isolated, comes from `using-git-worktrees` at execution time.

Announce: "Using the writing-plans skill to create the implementation plan."

## Scope

- One plan per independent subsystem — each must produce working, testable software alone. If the spec spans several, suggest splitting into separate plans.

## File structure (decide before tasks)

- Map every file to create/modify and its single responsibility — this locks in decomposition.
- One responsibility per file; prefer small focused files; files that change together live together (split by responsibility, not layer).
- Follow established codebase patterns. Restructure a file only when it's grown unwieldy AND you're already modifying it.

## Task right-sizing

- A task = the smallest unit that carries its own test cycle and is worth a fresh reviewer's gate.
- Fold setup/config/scaffolding/docs into the task whose deliverable needs them. Split only where a reviewer could reject one task while approving its neighbor.
- Each task ends with an independently testable deliverable.

## Step granularity

Each step is one 2-5 min action: write failing test → run it (confirm RED) → minimal implementation → run (confirm GREEN) → commit.

## Plan document shape

Header (required):

```markdown
# [Feature] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:subagent-driven-development (recommended) or superpowers:executing-plans. Steps use `- [ ]` checkboxes.

**Goal:** [one sentence]   **Architecture:** [2-3 sentences]   **Tech Stack:** [key libs]

## Global Constraints
[Project-wide spec requirements — version floors, dep limits, naming/copy rules,
platform — one line each, exact values verbatim. Every task implicitly includes this.]
```

Per task:

- **Files** — exact `Create:` / `Modify:path:lines` / `Test:` paths.
- **Interfaces** — `Consumes:` exact signatures from earlier tasks; `Produces:` exact names + param/return types later tasks rely on (implementers see only their own task).
- **Steps** — checkbox per step, with the ACTUAL test code, exact run command + expected output, the ACTUAL implementation code, and the commit.

## No placeholders (these are plan failures)

- "TBD"/"TODO"/"implement later"/"fill in details".
- "Add appropriate error handling / validation / edge cases".
- "Write tests for the above" without the test code; "similar to Task N" without repeating the code (tasks may be read out of order).
- Steps describing what without showing how (code steps need code blocks).
- References to types/functions/methods not defined in any task.

## Self-review (yourself, not a subagent)

1. **Spec coverage** — every spec requirement maps to a task; list + fill gaps.
2. **Placeholder scan** — hunt the patterns above; fix inline.
3. **Type consistency** — names/signatures in later tasks match earlier definitions (`clearLayers()` in T3 vs `clearFullLayers()` in T7 is a bug).

For a fresh-eyes pass, dispatch `plan-document-reviewer-prompt.md`.

## Execution handoff

Offer: **(1) Subagent-driven** (recommended) — `superpowers:subagent-driven-development`, fresh subagent per task + two-stage review; **(2) Inline** — `superpowers:executing-plans`, batch execution with checkpoints.

<!-- budget: ~74 -->

# Anthropic Skill-Authoring Best Practices

Public guidance — read at the source, not restated here:

- Superpowers original: <https://github.com/obra/Superpowers/blob/main/skills/writing-skills/anthropic-best-practices.md>
- Anthropic Agent Skills docs: <https://docs.anthropic.com> (search "Agent Skills")

## Non-obvious points worth keeping local

- **Description = WHEN, not WHAT.** A description that summarizes the workflow becomes a shortcut agents follow *instead of* reading the body — they do one step when the body says two. State triggering conditions only. (See `[[skill-authoring-contract]]` § description-SDO.)
- **Progressive disclosure is a hard budget, not a style.** SKILL.md loads into context; heavy reference (API dumps, 100+ line tables) lives in sibling files loaded on demand. Inline only what changes per task.
- **Name by the action / core insight, verb-first** — `condition-based-waiting` over `async-test-helpers`. Gerunds suit processes (`creating-skills`).
- **Cross-reference by skill name, never `@path`.** `@` force-loads the file immediately and burns context before it's needed. Use `**REQUIRED:** superpowers:test-driven-development`.
- **Automate mechanical constraints instead of documenting them.** If a regex/validator can enforce it, do that; reserve skill prose for judgment calls.
- **One excellent example beats five languages.** Complete, runnable, commented with WHY — not a fill-in-the-blank template.

For the canonical house contract (ordered-by-weight, description template, "match the form to the failure"), see `[[skill-authoring-contract]]`. For testing skills under pressure, see [testing-skills.md](testing-skills.md).

# Persuasion Principles for Skill Design

LLMs are parahuman — Cialdini's persuasion principles raise compliance the same way they do on people. Use them to make a discipline skill bind under pressure, not to manipulate.

- Sources: Cialdini, R. B. (2021). *Influence* (New & Expanded). Harper Business. — Meincke et al. (2025). *Call Me A Jerk: Persuading AI to Comply.* UPenn. (N=28,000; compliance 33% → 72%, p < .001; authority/commitment/scarcity strongest.)

## The six, as applied to bulletproofing a discipline skill

1. **Authority** — imperative + non-negotiable framing ("YOU MUST", "No exceptions") kills rationalization. Use for TDD/safety/verification rules.
2. **Commitment** — force an explicit choice or announcement ("Announce the skill", "Choose A/B/C", todos) so the agent stays consistent with it.
3. **Scarcity** — time-bind the action ("Before proceeding", "IMMEDIATELY after X") to defeat "I'll do it later".
4. **Social proof** — universal framing ("X without Y = failure. Every time.") sets the norm.
5. **Unity** — collaborative voice ("we're colleagues; I need your honest judgment") for non-hierarchical/guidance skills.
6. **Reciprocity / Liking** — DON'T use for compliance. Liking breeds sycophancy and conflicts with honest feedback; reciprocity reads as manipulation.

Pairings — discipline: authority + commitment + social proof. Guidance: light authority + unity. Reference: clarity only, zero persuasion.

Ethics test: would this serve the user's genuine interest if they fully understood it? If no, cut it.

#!/usr/bin/env node

/**
 * Render graphviz diagrams from a skill's SKILL.md to SVG files.
 *
 * Usage:
 *   ./render-graphs.js <skill-directory>           # Render each diagram separately
 *   ./render-graphs.js <skill-directory> --combine # Combine all into one diagram
 *
 * Extracts all ```dot blocks from SKILL.md and renders to SVG.
 * Useful for helping your human partner visualize the process flows.
 *
 * Requires: graphviz (dot) installed on system
 */

const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

function extractDotBlocks(markdown) {
  const blocks = [];
  const regex = /```dot\n([\s\S]*?)```/g;
  let match;

  while ((match = regex.exec(markdown)) !== null) {
    const content = match[1].trim();

    // Extract digraph name
    const nameMatch = content.match(/digraph\s+(\w+)/);
    const name = nameMatch ? nameMatch[1] : `graph_${blocks.length + 1}`;

    blocks.push({ name, content });
  }

  return blocks;
}

function extractGraphBody(dotContent) {
  // Extract just the body (nodes and edges) from a digraph
  const match = dotContent.match(/digraph\s+\w+\s*\{([\s\S]*)\}/);
  if (!match) return '';

  let body = match[1];

  // Remove rankdir (we'll set it once at the top level)
  body = body.replace(/^\s*rankdir\s*=\s*\w+\s*;?\s*$/gm, '');

  return body.trim();
}

function combineGraphs(blocks, skillName) {
  const bodies = blocks.map((block, i) => {
    const body = extractGraphBody(block.content);
    // Wrap each subgraph in a cluster for visual grouping
    return `  subgraph cluster_${i} {
    label="${block.name}";
    ${body.split('\n').map(line => '  ' + line).join('\n')}
  }`;
  });

  return `digraph ${skillName}_combined {
  rankdir=TB;
  compound=true;
  newrank=true;

${bodies.join('\n\n')}
}`;
}

function renderToSvg(dotContent) {
  try {
    return execSync('dot -Tsvg', {
      input: dotContent,
      encoding: 'utf-8',
      maxBuffer: 10 * 1024 * 1024
    });
  } catch (err) {
    console.error('Error running dot:', err.message);
    if (err.stderr) console.error(err.stderr.toString());
    return null;
  }
}

function main() {
  const args = process.argv.slice(2);
  const combine = args.includes('--combine');
  const skillDirArg = args.find(a => !a.startsWith('--'));

  if (!skillDirArg) {
    console.error('Usage: render-graphs.js <skill-directory> [--combine]');
    console.error('');
    console.error('Options:');
    console.error('  --combine    Combine all diagrams into one SVG');
    console.error('');
    console.error('Example:');
    console.error('  ./render-graphs.js ../subagent-driven-development');
    console.error('  ./render-graphs.js ../subagent-driven-development --combine');
    process.exit(1);
  }

  const skillDir = path.resolve(skillDirArg);
  const skillFile = path.join(skillDir, 'SKILL.md');
  const skillName = path.basename(skillDir).replace(/-/g, '_');

  if (!fs.existsSync(skillFile)) {
    console.error(`Error: ${skillFile} not found`);
    process.exit(1);
  }

  // Check if dot is available
  try {
    execSync('which dot', { encoding: 'utf-8' });
  } catch {
    console.error('Error: graphviz (dot) not found. Install with:');
    console.error('  brew install graphviz    # macOS');
    console.error('  apt install graphviz     # Linux');
    process.exit(1);
  }

  const markdown = fs.readFileSync(skillFile, 'utf-8');
  const blocks = extractDotBlocks(markdown);

  if (blocks.length === 0) {
    console.log('No ```dot blocks found in', skillFile);
    process.exit(0);
  }

  console.log(`Found ${blocks.length} diagram(s) in ${path.basename(skillDir)}/SKILL.md`);

  const outputDir = path.join(skillDir, 'diagrams');
  if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir);
  }

  if (combine) {
    // Combine all graphs into one
    const combined = combineGraphs(blocks, skillName);
    const svg = renderToSvg(combined);
    if (svg) {
      const outputPath = path.join(outputDir, `${skillName}_combined.svg`);
      fs.writeFileSync(outputPath, svg);
      console.log(`  Rendered: ${skillName}_combined.svg`);

      // Also write the dot source for debugging
      const dotPath = path.join(outputDir, `${skillName}_combined.dot`);
      fs.writeFileSync(dotPath, combined);
      console.log(`  Source: ${skillName}_combined.dot`);
    } else {
      console.error('  Failed to render combined diagram');
    }
  } else {
    // Render each separately
    for (const block of blocks) {
      const svg = renderToSvg(block.content);
      if (svg) {
        const outputPath = path.join(outputDir, `${block.name}.svg`);
        fs.writeFileSync(outputPath, svg);
        console.log(`  Rendered: ${block.name}.svg`);
      } else {
        console.error(`  Failed: ${block.name}`);
      }
    }
  }

  console.log(`\nOutput: ${outputDir}/`);
}

main();

---
name: writing-skills
description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
---

# Writing Skills

Writing a skill IS TDD on process documentation: watch an agent fail the task WITHOUT the skill (RED), write the skill against those exact failures (GREEN), close the loopholes it then invents (REFACTOR). If you never watched it fail without the skill, you don't know the skill teaches the right thing.

Vendored from [obra/Superpowers](https://github.com/obra/Superpowers) (MIT, Jesse Vincent), compressed to house style per `[[vendored-skill-compression]]`.

**REQUIRED BACKGROUND:** superpowers:test-driven-development defines the RED-GREEN-REFACTOR cycle this adapts.

## Authoring contract lives in one canonical place

Ordered-by-weight bullets, the behavior-anchored `description` template, description-SDO (WHEN not WHAT), and "match the form to the failure" are the house authoring contract — see `[[skill-authoring-contract]]`, don't restate them. Token-efficient prose style: `[[instruction-compression-playbook]]`. This file covers only what's specific to *creating + testing* a skill.

## What a skill is

A reference guide for a proven technique, pattern, or tool — reusable, not a narrative of how you solved something once. Three shapes:

- **Technique** — a concrete method with steps (`condition-based-waiting`, `root-cause-tracing`).
- **Pattern** — a way of thinking about a class of problem (`flatten-with-flags`).
- **Reference** — API/syntax/tool docs.

## When to create one

- Create when: the technique wasn't obvious to you, you'd reuse it across projects, and it applies broadly.
- Don't create for: one-offs, things well-documented elsewhere, project-specific conventions (put those in the instructions file), or anything a regex/validator can enforce — automate that instead of documenting it.

## Iron Law

NO SKILL — OR EDIT — SHIPS WITHOUT A FAILING TEST FIRST. Wrote it before testing? Delete it, start from baseline. No exception for "simple additions", "just a section", or "documentation updates". Don't keep untested changes "as reference". Delete means delete.

## Structure

Two required frontmatter fields: `name` (letters/numbers/hyphens only) and `description` (≤1024 chars total; see [agentskills.io/specification](https://agentskills.io/specification) for the rest). Then a lean body:

```markdown
## Overview        # what + core principle, 1-2 sentences
## When to Use     # symptoms / use cases; when NOT to; small flowchart only if the decision is non-obvious
## Core Pattern    # before/after for techniques & patterns
## Quick Reference # table or bullets for scanning
## Implementation  # inline code for simple cases; link a file for heavy reference
## Common Mistakes # what goes wrong + the fix
```

SKILL.md is a table of contents (progressive disclosure). Inline only what changes per task; split out when content is heavy:

- **Heavy reference** (100+ lines of API/syntax) → its own file, loaded on demand.
- **Reusable tool** (script, template) → its own file.
- Keep inline: principles, concepts, code patterns under ~50 lines.

Cross-reference other skills by name with an explicit marker (`**REQUIRED:** superpowers:test-driven-development`) — never `@path`, which force-loads the file and burns 200k+ context before you need it.

## Code examples

One excellent example beats five languages. Make it complete, runnable, from a real scenario, commented with WHY — not a fill-in-the-blank template. You're good at porting; one great example is enough.

## Flowcharts

Use a small inline flowchart ONLY for a non-obvious decision point, a process loop where you might stop too early, or an "A vs B" choice. Never for reference material (use tables/lists), code (use markdown blocks), or linear steps (use a numbered list). Style rules: `graphviz-conventions.dot`. Render for a human: `./render-graphs.js ../some-skill [--combine]`.

## Testing & bulletproofing

The full method — pressure scenarios, the RED-GREEN-REFACTOR loop for skills, rationalization tables, red-flags, micro-testing wording against a no-guidance control, and the per-skill deployment gate — lives in **[testing-skills.md](testing-skills.md)**. A worked campaign is in [examples/CLAUDE_MD_TESTING.md](examples/CLAUDE_MD_TESTING.md). Persuasion levers that make a discipline skill bind: persuasion-principles.md.

The one-line discipline: discipline/judgment skills get pressure-tested under 3+ stacked pressures; pure reference skills get retrieval-tested instead.

## See

- [testing-skills.md](testing-skills.md) — the testing + bulletproofing method
- anthropic-best-practices.md — pointer to Anthropic's public authoring guide + local deltas
- persuasion-principles.md — Cialdini levers for compliance under pressure
- `[[skill-authoring-contract]]` — the canonical authoring contract (structure, description template, form-to-failure)
- `[[instruction-compression-playbook]]` — token-efficient prose style
- `[[micro-test-instruction-wording]]` — prove guidance wording binds before shipping it

## Rationalizations — all mean "test first"

| Excuse | Reality |
|---|---|
| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |
| "Just a reference" | References have gaps. Test retrieval. |
| "Too tedious to test" | Less tedious than debugging a bad skill in production. |
| "I'll test if problems emerge" | Problems = agents can't use the skill. Test BEFORE deploying. |

**Red Flags — STOP and test:** "just a simple addition" · "I'm confident it's good" · "academic review is enough" · "no time to test."

<!-- budget: ~77 -->

# Testing Skills

Merges the testing + bulletproofing method from the vendored [obra/Superpowers](https://github.com/obra/Superpowers) writing-skills (MIT, Jesse Vincent). The technique, not the prose.

Testing a skill is TDD on process documentation: run the scenario WITHOUT the skill (RED — watch the agent fail), write the skill against those exact failures (GREEN), close the new loopholes the agent finds (REFACTOR). If you never watched an agent fail without it, you don't know the skill prevents the right thing.

**REQUIRED BACKGROUND:** superpowers:test-driven-development defines RED-GREEN-REFACTOR. This adapts it to docs.

## Iron Law

NO SKILL — OR EDIT — SHIPS WITHOUT A FAILING TEST FIRST. Wrote it before testing? Delete it, start from baseline. Applies to "simple additions" and "just a section" too.

## What to test (and what not to)

- Test skills that enforce discipline, carry a compliance cost (time, rework), or can be rationalized away under pressure.
- Don't pressure-test pure reference skills (API/syntax). Test those for *retrieval* instead: can an agent find the right entry and apply it? Are common cases covered?

## Match the form to the failure (do this BEFORE writing guidance)

Classify the baseline failure first — the form that fixes one type backfires on another. (Canonical version: `[[skill-authoring-contract]]`.)

| Baseline failure | Right form | Wrong form |
|---|---|---|
| Knows the rule, skips it under pressure | Prohibition + rationalization table + red flags | Soft guidance ("prefer…", "consider…") |
| Complies but output is wrong-shaped (bloated, buried verdict, restated spec) | Positive recipe: state what the output IS, its parts in order | Prohibition ("don't restate", "never narrate") |
| Omits a required element it already produces | Structural: a REQUIRED slot in the template | Prose reminder near the template |
| Behavior should depend on a condition | Conditional on an observable predicate | Unconditional rule + exemption clauses |

- **Prohibitions backfire on shaping problems.** Under a competing incentive the agent negotiates with "don't X"; in head-to-head wording tests the prohibition arm produced *more* unwanted content than even the no-guidance control. A recipe leaves nothing to negotiate.
- **No nuance clauses.** "Don't X unless it matters" reopens the negotiation — it turned a consistent recipe noisy in the same tests. Express a real exception as its own conditional.
- **Exemption clauses don't scope.** "Doesn't apply to code blocks" still suppresses code blocks. Restructure so the rule can't reach the exempt part.

## RED — baseline

Run a pressure scenario WITHOUT the skill. A good scenario:

- Combines 3+ pressures (single pressure is resisted; stacked pressure breaks). Types: time, sunk cost, authority, economic, exhaustion, social, "being pragmatic not dogmatic".
- Forces a concrete A/B/C choice — no open-ended "what should you do", no deferring to "I'd ask the human".
- Uses real paths, real times, real consequences. Frame it as real work, not a quiz ("This is a real scenario. Choose and act.").

Document choices and rationalizations **verbatim** — "the agent was wrong" tells you nothing; "Tests after achieve same goals" tells you exactly what to counter. Note which pressures triggered the violation.

## GREEN — minimal skill

Write only enough to address the failures you actually observed; no content for hypothetical cases. Re-run the same scenarios WITH the skill. Still failing → the skill is unclear or incomplete, not the agent.

## REFACTOR — close loopholes

For each NEW rationalization the agent invents:

1. **Explicit negation** — don't just state the rule, forbid the workaround. `Delete it.` → `Delete it. Start over. Don't keep it as "reference", don't "adapt" it, don't look at it. Delete means delete.`
2. **Rationalization table row** — `| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |`
3. **Red-flag entry** — a self-check list of phrases that mean STOP ("I already manually tested it", "spirit not letter", "this is different because…").
4. **Foundational principle, stated early** — `Violating the letter of the rules is violating the spirit.` kills a whole class of "I'm following the spirit" outs.
5. **Update the description** with the symptoms of being ABOUT to violate.

Re-test the same scenarios. Bulletproof when, under maximum pressure, the agent picks the right option, cites the skill, and acknowledges the temptation but holds. Not bulletproof if it invents new rationalizations, argues the skill is wrong, or builds a "hybrid".

### Micro-test the wording before full scenarios

Full pressure runs are the final gate but slow. Verify the wording first (raw API call or single-shot subagent):

- System prompt = the realistic context the guidance lives in (the whole skill/template, not the line in isolation); user message = a task that tempts the failure.
- **Always include a no-guidance control.** If the control doesn't fail, there's nothing to fix — don't author guidance. (See `[[micro-test-instruction-wording]]`.)
- 5+ reps per variant — single samples lie. Read every flagged match by hand; template echoes and quoted counter-examples masquerade as hits.
- **Variance is the metric.** When wording binds, reps converge on one shape. Five interpretations across five reps = tighten the form before adding words.

### Meta-test when GREEN won't hold

Ask the failing agent: "You read the skill and chose C anyway — how should it have been written so A was the only acceptable answer?" Three answers map to three fixes: "it was clear, I ignored it" → add a stronger foundational principle; "it should have said X" → add X verbatim; "I didn't see section Y" → make Y more prominent / move it earlier.

## Rationalizations for skipping testing — all mean "test first"

| Excuse | Reality |
|---|---|
| "Obviously clear" | Clear to you ≠ clear to other agents. |
| "Just a reference" | References have gaps. Test retrieval. |
| "I'll test if problems emerge" | Problems = agents can't use it. Test before deploy. |
| "I'm confident it's good" | Overconfidence guarantees issues. |

## STOP — per-skill deployment gate

After writing ANY skill, finish it before starting the next. No batching untested skills "for efficiency". Deploying an untested skill = deploying untested code.

Checklist: baseline ran + rationalizations captured verbatim · form matches the failure type · behavior-shaping wording micro-tested vs a control · description is "Use when…" triggers-only, third person, keyword-rich · one runnable example (not multi-language) · WITH-skill re-test passes under max pressure · rationalization table + red-flags built from real iterations · commit + push.

## Anti-patterns

- Narrative example ("in session 2025-10-03 we…") — too specific, not reusable.
- Multi-language dilution (example.js + .py + .go) — mediocre, maintenance burden.
- Code or generic labels (`step1`, `helper2`) in flowcharts — unreadable, no semantic meaning.
- Vague counters ("don't cheat") — only specific negations ("don't keep as reference") bind.
- Stopping after one passing run — passing once ≠ bulletproof.

## See

- [examples/CLAUDE_MD_TESTING.md](examples/CLAUDE_MD_TESTING.md) — worked test campaign over CLAUDE.md variants
- persuasion-principles.md — why authority/commitment/scarcity raise compliance
- `[[skill-authoring-contract]]` · `[[instruction-compression-playbook]]` · `[[micro-test-instruction-wording]]`