wolfplan

name	wolfplan
description	MANDATORY planning technique that prevents orphaned implementations through negative planning (pre-mortem) and inverse planning (connection audit)
version	1.4.0
triggers	["planning","implementation plan","before coding","design phase","writing plan","EnterPlanMode"]

Wolfplan: Negative + Inverse Planning System

MANDATORY PROTOCOL - Prevents orphaned implementations

This skill enforces two planning techniques that prevent the "textbook smart, system dumb" antipattern where code gets implemented but never wired into the larger system.

The Problem Wolfplan Solves

AI assistants frequently:

• Implement code that's never wired in
• Write tests that never run in CI
• Create services that nothing knows about
• Add config that's never loaded
• Build features users can't reach

Root cause: Forward-only planning without validation of system integration.

When to Use This Skill

ALWAYS use wolfplan if:

• Any file CRUD (create, read for modification, update, delete)
• Any side effects (API calls, DB writes, config changes)
• Any new functionality
• Any modification to existing functionality

SKIP wolfplan only if:

• Pure data fetching (read-only, no changes)
• Answering a question (no code changes)

"Too simple" is not an excuse. Small changes cause big orphans.

---

How Wolfplan Works

Step 0: Enter Plan Mode (FIRST)

IMMEDIATELY invoke the EnterPlanMode tool to switch into plan mode.

Use EnterPlanMode tool → System switches to read-only planning state

This ensures:

• No code changes happen before planning is complete
• The system enforces the planning workflow
• You can explore the codebase safely

Do NOT proceed to Step 1 until plan mode is active.

---

MANDATORY: Subagents & Background Tasks

Work MUST be done via subagents, not inline.

During planning:

1. Use Explore agents to understand the codebase
2. Use Plan agents to design implementation approaches
3. ALL Task invocations MUST use run_in_background: true

Task tool:
  - subagent_type: "Explore" (or "Plan")
  - run_in_background: true   ← REQUIRED
  - prompt: "..."

Why subagents:

• Parallel exploration is faster
• Multiple agents can run simultaneously
• Specialized agents (Explore, Plan) do focused work
• Main thread stays responsive

Enforcement: If you catch yourself doing work inline instead of dispatching a subagent, STOP and dispatch it.

Use TaskOutput with block: true only when you need results to continue.

---

Worktrees for Isolation

If the work requires code isolation (feature branches, experiments, risky changes):

1. Load the worktree skill: Skill tool → superpowers:using-git-worktrees
2. Create worktree before implementation begins
3. Document worktree in the plan metadata

# In plan frontmatter
worktree: /path/to/worktree
branch: feature/my-feature

When to use worktrees:

• New features that might break existing code
• Experiments or spikes
• Work that needs isolation from main branch
• Parallel development tracks

---

Load Relevant Skills

After determining what the task requires, load any skills that will help:

1. Analyze the task - what domains does it touch?
2. Check available skills - what skills exist for those domains?
3. Load them - use Skill tool to load relevant skills
4. Document in plan - list loaded skills in plan metadata

# In plan frontmatter
skills_loaded:
  - wolfplan
  - superpowers:using-git-worktrees
  - wolf-workflows
  - [domain-specific skills]

Common skill patterns:

• Frontend work → load frontend-related skills
• API work → load API/backend skills
• Testing → load TDD skills
• Trading/market data → load databento, trading skills
• Security → load security-focused skills

The plan must document which skills were loaded and why.

---

Step 1: Detect Personality

Before planning, detect active personality:

1. Check $CLAUDE_INSTANCE environment variable
2. If set: Read ~/.claude/instances/$CLAUDE_INSTANCE/personality.json
3. If not: Read ~/.claude/personality.json
4. Extract "active" field (e.g., "mordecai")
5. Load personality profile from ~/.claude/plugins/marketplaces/wolf-skills-marketplace/personality/profiles/

Wolfplan COMBINES with personality - it does NOT override personality style.

Step 2: Check Plan State

wolfplan invoked
    │
    ├─ No existing plan in ~/.claude/plans/?
    │     → Create new plan with metadata
    │
    ├─ Existing plan, same scope?
    │     → Update plan (append to log)
    │
    └─ Existing plan, DIFFERENT scope?
          → Archive to ~/.claude/plans/archive/YYYY-MM-DD-<name>.md
          → Create fresh plan for new scope

Step 3: Run Negative Planning (Pre-mortem)

Complete ALL items before proceeding:

[ ] 1.1 PREMISE CHECK
    Ask yourself:
    - Is this the right solution to the problem?
    - Is there a simpler approach we're missing?
    - What are we assuming that might be wrong?
    - Should this even be built?

[ ] 1.2 FAILURE MODES
    Identify what could:
    - Crash or throw exceptions?
    - Fail silently (no error, wrong result)?
    - Produce incorrect results without any indication?

[ ] 1.3 EDGE CASES
    Consider:
    - Empty/null/undefined inputs?
    - Concurrent access / race conditions?
    - Large scale / performance limits?
    - State transitions that shouldn't be possible?

[ ] 1.4 DEPENDENCIES
    Audit external risks:
    - External APIs that could change or be unavailable?
    - Libraries that could have breaking updates?
    - Services that could be down?
    - Data that could be malformed or missing?

[ ] 1.5 SIDE EFFECTS & RAMIFICATIONS
    Map the impact:
    - What existing functionality might this break?
    - What other systems/services need to know about this?
    - What migrations or data changes are implied?
    - What documentation becomes stale?

Step 4: Run Inverse Planning (Connection Audit)

Complete ALL items before proceeding:

[ ] 2.1 DEFINE "DONE" STATE
    Be specific:
    - What does "a user can actually use this" look like?
    - What is the exact interaction path from entry point to feature?
    - What confirms success (not just "no errors")?

[ ] 2.2 WORK BACKWARDS (Reverse Chain)
    For the user to do X, what MUST be true?

    Start from user action, trace backwards:
    □ UI/CLI/API endpoint exists and is accessible?
    □ Route is registered/exposed?
    □ Service layer knows about this?
    □ Business logic is wired in?
    □ Data layer is connected?
    □ Config/feature flags are set?

[ ] 2.3 ORPHAN DETECTION (CRITICAL)
    List EVERY artifact this plan creates:

    | Artifact | How is it reached? |
    |----------|-------------------|
    | [file/function/class] | [what calls/imports it] |
    | [test file] | [how it runs in CI] |
    | [config entry] | [where it's loaded] |
    | [migration] | [when it runs] |

    For EACH artifact, answer: "What calls/imports/loads this?"

    If answer is "nothing yet" → MUST add wiring step to plan

[ ] 2.4 INTEGRATION VERIFICATION
    Confirm wiring exists:
    □ Routes/endpoints registered?
    □ Services injected/imported where needed?
    □ Config files updated?
    □ Feature flags wired (if applicable)?
    □ UI navigation updated (if user-facing)?
    □ Documentation updated?
    □ Tests actually run in CI (not just exist)?

Step 5: Update Plan File

Append wolfplan analysis to the plan. See Output Format below.

Step 6: Output Summary

Report to user in personality voice, ending with TL;DR:

[PERSONALITY] cast wolfplan on your behalf, Jeremy.

Updated the plan with:
- Pre-mortem: [count] risks identified, [count] mitigations added
- Connection audit: [count] artifacts checked, [count] orphans found
- Wiring: Added [count] integration steps
- Skills loaded: [list]
- Subagents dispatched: [count]

Plan file: ~/.claude/plans/[name].md

---

**TL;DR**: [One sentence summary of what the plan does and the key risk/decision]

---

TL;DR Format (MANDATORY - LAST OUTPUT)

Every wolfplan output MUST end with a TL;DR.

The TL;DR must be:

• One sentence (two max if complex)
• Action-oriented - what will be done
• Risk-aware - mention the biggest risk or key decision
• LAST thing output - always at the very bottom

Examples:

TL;DR: Adding user preferences API with auth middleware; main risk is rate limiting config.

TL;DR: Refactoring payment service into separate module; using worktree to avoid breaking checkout.

TL;DR: Implementing Discord webhook; 2 orphans found (route + config) now have wiring steps.

Enforcement: If your output doesn't end with TL;DR, you're not done.

---

Red Flags - STOP

If you catch yourself thinking:

• "I'll wire it in later" → NO. Plan the wiring NOW. Later never comes.
• "This is obviously going to work" → Run pre-mortem anyway. Obvious things fail.
• "The user will figure out how to use it" → Audit the access path. Don't assume.
• "Tests exist, so it's fine" → Do tests RUN? In CI? Or just exist?
• "It's just a small change" → Small changes cause the biggest orphans.
• "The config is obvious" → WHO loads it? WHEN? Trace it.
• "I already know the answer" → Document it anyway. Future you won't remember.
• "This is too simple for full process" → Wrong. Simple is when orphans hide.
• "I'll just run this task inline" → NO. ALL tasks run in background during planning.
• "I don't need subagents for this" → YES you do. Dispatch Explore/Plan agents.
• "Worktrees are overkill" → If there's any risk of breaking main, use a worktree.
• "I know what skills I need" → Document them in the plan anyway.
• "The summary is enough" → NO. End with TL;DR. Always.

STOP. Run the full checklist. Every time.

---

Output Format

What Gets Written to Plan File

Wolfplan appends a timestamped log entry:

### [YYYY-MM-DDTHH:MM] Wolfplan Analysis

**Cast by**: [PERSONALITY] on behalf of Jeremy

#### Pre-mortem Findings

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| [identified risk] | H/M/L | H/M/L | [what to do about it] |

#### Premise Validation

- [ ] This IS the right approach because: [reason]
- OR
- [ ] Consider alternative: [simpler approach worth exploring]

#### Connection Audit

| Artifact | Connected Via | Verified |
|----------|---------------|----------|
| [file/function] | [what calls/imports it] | ✅/❌ |

#### Wiring Steps Added to Plan

1. [specific step to connect artifact]
2. [specific step to register route]
3. [specific step to update config]
...

#### Orphan Risk Assessment

**Risk Level**: LOW / MEDIUM / HIGH

[Explanation of orphan risk and what's being done about it]

---

Plan File Structure

New plans are created with this structure:

---
project: <detected or user-specified project name>
user: Jeremy
personality: <active personality from config>
created: <ISO timestamp>
last_updated: <ISO timestamp>
status: active
original_goal: "<what user initially asked for>"
evolved_goal: "<current understanding, if changed>"
---

# [Project Name] - Wolfplan

## Goal Evolution Log

| Timestamp | Change | Reason |
|-----------|--------|--------|
| [timestamp] | Initial goal set | User request |

## Personality Log

| Timestamp | Personality | Note |
|-----------|-------------|------|
| [timestamp] | [personality] | Started plan |

## Update Log (append-only)

### [timestamp] Initial Plan

[original plan content]

### [timestamp] Wolfplan Analysis Applied

[pre-mortem and connection audit results]

---

Integration with Other Skills

Wolfplan chains WITH (not instead of):

• wolf-session-init → Load principles/archetype/governance first
• wolf-workflows → Wolfplan runs during planning phase
• writing-plans → Wolfplan output feeds into plan document
• brainstorming → Wolfplan runs after design approved, before implementation plan

Wolfplan does NOT replace:

• Role-specific planning (architect, coder, etc.)
• Domain-specific validation
• Code review

---

Good/Bad Examples

Good Example: Using Wolfplan

**Scenario**: Adding a new API endpoint for user preferences

Wolfplan Actions:

1. Pre-mortem: Identified risks - auth could fail, preferences could be empty, rate limiting needed
2. Connection Audit:
   • Artifact: preferencesController.ts → Connected via: route registration in routes/index.ts ✅
   • Artifact: preferencesService.ts → Connected via: import in controller ✅
   • Artifact: preferences.test.ts → Connected via: jest config, runs in CI ✅
3. Wiring steps added:
   • Add route to routes/index.ts
   • Add OpenAPI spec entry
   • Add rate limit config

Result: No orphans. Feature is accessible. Tests run.

Bad Example: Skipping Wolfplan

**Scenario**: Adding a new API endpoint for user preferences

Actions without Wolfplan:

1. Created preferencesController.ts
2. Created preferencesService.ts
3. Created preferences.test.ts
4. Committed code
5. Later discovered:
   • Route was never registered (orphan controller)
   • Tests existed but weren't in CI config (orphan tests)
   • No OpenAPI spec (undocumented endpoint)
   • Auth middleware wasn't applied (security hole)

Result: 2 days of debugging "why doesn't this endpoint work?"

---

Verification Checklist

Before claiming wolfplan is complete:

• Pre-mortem: All 5 sections addressed
• Inverse planning: All 4 sections addressed
• Every artifact has documented connection
• No orphans identified (or wiring steps added for each)
• Plan file updated with timestamped entry
• Summary output to user in personality voice

Can't check all boxes? Wolfplan incomplete. Continue.

---

Version History

• v1.4.0 (2025-03-29): Add mandatory TL;DR as last output - one sentence summary with key risk
• v1.3.0 (2025-03-29): Enforce subagents, worktrees, and skill loading - work must be delegated
• v1.2.0 (2025-03-29): Enforce background tasks - all Task invocations must use run_in_background: true
• v1.1.0 (2025-03-29): Add EnterPlanMode as Step 0 - wolfplan now switches to plan mode first
• v1.0.0 (2025-03-29): Initial release with negative planning + inverse planning

---

Wolfplan prevents the gap between "code exists" and "feature works."