bits-plan

What this skill does

# Bits Planning Skill

Review the conversation history above to identify work that needs planning. Extract requirements, decisions, and context discussed—these inform the bits tasks you create. If the user provided additional instructions below, incorporate those as well.

## When to Use This Skill

| Scenario | Approach |
|----------|----------|
| Complex multi-step implementation | Use this skill for structured planning |
| Breaking down large features into tasks | Use this skill with debate refinement |
| Simple single-task work | Use bits skill directly |
| Quick research or exploration | Use Explore agent |

This is a three-phase process: discovery, planning with collaborative debate, then task creation with a mandatory goal contract.

## Phase 1: Discovery

Gather context from the conversation history and find verification commands.

### Step 1: Verification Commands
Run a focused Explore query to discover development commands. This may return nothing, especially for new projects—in which case, simply create tasks without verification sections.
```
Find the ACTUAL commands used in this project for verification. Search in order:
1. mise.toml / .mise.toml (mise task runner - https://github.com/jdx/mise)
2. package.json scripts / pyproject.toml / Makefile / Justfile
3. .github/workflows (CI jobs are authoritative)
4. docs/CONTRIBUTING.md or README.md

For each category, report the EXACT command string:
- Linting/formatting (e.g., `mise run lint`, `go fmt ./...`)
- Static analysis / type checking (e.g., `mise run check`, `staticcheck ./...`, `golangci-lint run`)
- Unit tests (e.g., `mise run test`, `go test ./...`)
- Scoped E2E tests - run specific tests (e.g., `mise run test:e2e -- -run TestAuth`, `go test ./e2e/... -run TestAuth`)
- Full E2E tests - run entire suite (e.g., `mise run test:e2e`, `go test ./e2e/...`)

Output format: "CATEGORY: [exact command]"
Stop searching a category once you find an authoritative source.
```

### Step 2: Discovery Synthesis
Consolidate findings from conversation history into planning input:
- **Architecture overview**: Patterns, conventions, and constraints discussed
- **Testing setup**: Where tests live, how to run them, what coverage exists
- **Verification commands**: From Step 1
- **Known risks**: Edge cases and caveats identified

This synthesis becomes the input for Phase 2.

## Phase 2: Planning with Collaborative Debate

Use multi-round refinement for thorough planning.

### Guiding Principles: Speed-of-Light Implementation

**Treat planning as a minimization problem.** The goal is not to design a comprehensive solution—it's to find the smallest, fastest path to the desired outcome.

- **Minimize changes**: What is the absolute minimum number of lines, files, and touch points needed? Every additional change is a potential bug, a review burden, and merge conflict risk.
- **Minimize complexity**: Prefer boring, obvious solutions over clever ones. If two approaches work, choose the one a junior developer could understand in 5 minutes.
- **Minimize scope**: Ruthlessly cut anything that isn't strictly required. "Nice to have" belongs in a separate future task, not this plan.
- **Minimize risk**: Favor incremental changes over big-bang rewrites. Ship something small that works over something ambitious that might not.

**Ask at every decision point**: "Is there a simpler way?" If the answer is yes, take it.

### Step 1: Initial Plan
Use the Plan subagent with **model: "opus"** to design the minimum viable implementation based on discovery synthesis. The plan should answer: "What is the smallest change that achieves the goal?"

### Step 2: Interview Codex

Use threaded conversations to probe and refine the plan. Claude interviews Codex, asking probing questions to surface gaps, risks, and simplification opportunities.

**Start the thread:**
Use `mcp__codex__codex` to share the initial plan and begin the interview. Inform Codex of your capabilities so it can request specific research:
```
prompt: "I'm planning this implementation: [plan].

I can run multiple parallel sub-agents to gather information:
- Explore agents to search the codebase and answer specific questions
- Plan agents for deeper architectural analysis

Help me think through this critically. What concerns do you have? What might I be missing? Are there specific questions I should investigate with an Explore agent before proceeding?"
```

**Probe deeper:**
Continue with `mcp__codex__codex-reply` using the returned `threadId`. Ask about literally anything: technical implementation, concerns, tradeoffs, edge cases, assumptions, risks, dependencies.

Questions should not be obvious—probe deeper into things that might not have been considered:
- "What's the hardest part of this?"
- "Where could this break in production?"
- "What assumptions am I making that might be wrong?"
- "Is there a simpler way to achieve this?"
- "What would you cut if you had to ship this in half the time?"

Challenge assumptions. Ask about the hard parts. Push back when answers feel incomplete.

**Continue until the plan is fully fleshed out:**
There's no fixed number of rounds. Keep interviewing until:
- Major concerns have been addressed or explicitly deferred
- The plan feels minimal and well-understood
- You're confident it represents the smallest viable implementation

**Synthesize insights:**
After the interview, integrate Codex's feedback into the final plan. Document what was deferred and why.

### Step 3: Draft the Goal Contract

Before creating any tasks, translate the user's request into a **Goal Contract**: 3-7 observable truths that must ALL be proven true for the work to be considered done.

**If the user's request is ambiguous** and you cannot write concrete, verifiable contract lines, STOP and ask the user for clarification. Do not create a Replan task — ambiguity requires user input.

The goal contract must be:
- **Observable**: Each line can be verified by running a command, inspecting a file, or testing behavior
- **Concrete**: No vague qualifiers like "properly handles" or "works correctly" — state what specifically must be true
- **Complete**: If all lines are true, the original request is satisfied

Example for "add auth to the API":
1. `POST /login` returns a JWT for valid credentials and 401 for invalid
2. Protected endpoints return 403 when no token is provided
3. Protected endpoints succeed with a valid token
4. Token expiration is enforced (expired tokens return 401)
5. Tests exist covering login success, login failure, protected access, and token expiration
6. `mise run lint` and `mise run test` pass

### Quality Gate
Before creating tasks, confirm:
- Goal contract lines are specific and verifiable
- All discovered edge cases addressed or explicitly deferred with rationale
- Error paths defined (what happens when X fails?)
- Testing strategy covers new code
- Trade-offs documented with reasoning

## Phase 3: Create Tasks

### Step 1: Create the Root Verification Task FIRST

This is mandatory. Create it before any implementation tasks so its ID is available for dependency wiring.

```bash
bits add "Verify goal: <concise goal summary>" -p high -d "<goal contract description>" --json
```

The description must contain four sections:

```markdown
# Original Request
<The user's original request, verbatim or faithfully paraphrased>

# Goal Contract
Each line must be proven true to close this task:
1. <observable truth 1>
2. <observable truth 2>
...

# Allowed Evidence
For each contract line, the verifier must cite one of:
- A closed child verification task that proves the line
- Command output demonstrating the behavior
- Specific file content or test results

Vibe-checking is not evidence. Each line needs explicit proof.

# Failure Handling
- If a contract line is false: create a new blocker bit, add it as a dependency, release this task
- If a contract line is ambiguous: create a Replan task and stop drain
- Track rounds via [goal:<this_task_id>][round:N]