writing-plans

What this skill does

# Writing Plans

## External Documentation Search (First Step)

Before researching the codebase, offer to search external documentation for the latest API references using Context7 MCP.

### Step 0: Check Context7 Availability

First, check if Context7 MCP tools are available by looking for `mcp__context7__` tools in your available tools list.

**If Context7 is NOT available:**

- Skip this entire section silently
- Proceed directly to Python Project Detection
- Do NOT ask the user about documentation search

**If Context7 IS available:**

- Continue with Step 1

### Step 1: Ask About Documentation

Use AskUserQuestion:

```
Question: "Would you like me to search external documentation before planning?"
Header: "Docs"
multiSelect: false
Options:
- Yes, let me specify: I'll enter which libraries/frameworks to search
- Auto-detect from task: Analyze the task and search relevant libraries automatically
- No, skip: Proceed with planning without external docs
```

### Step 2: Get Library Names

**If user selected "Yes, let me specify":**

- Ask follow-up: "Which libraries/frameworks should I search? (comma-separated, e.g., 'fastapi, pydantic, sqlalchemy')"

**If user selected "Auto-detect from task":**

- Extract technology keywords from the task description
- Present detected libraries for confirmation: "I detected these technologies: [list]. Should I search docs for these?"

**If user selected "No, skip":**

- Proceed directly to Python Project Detection

### Step 3: Fetch Documentation

For each library the user confirms:

1. **Resolve library ID:**

   ```
   mcp__context7__resolve-library-id(libraryName: "library-name")
   ```

   Select the most relevant match based on description and documentation coverage.

2. **Fetch relevant docs:**

   ```
   mcp__context7__get-library-docs(
     context7CompatibleLibraryID: "/org/project",
     topic: "[relevant topic from task]",
     mode: "code"
   )
   ```

   Use `mode: "info"` for architectural/conceptual questions.

3. **Use for context only:**
   Keep documentation in working memory to inform plan tasks. Do NOT include raw docs in the plan document.

**If tool call fails:** Inform user that Context7 couldn't fetch docs for that library and continue with available information.

### Step 4: Continue to Planning

After documentation is loaded (or skipped), proceed to Python Project Detection with documentation context available.

---

## Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."

## Python Project Detection

Before writing a plan, detect if this is a Python project and what framework it uses:

**Detection signals:**

- `pyproject.toml` or `setup.py` → Python project
- `fastapi` in dependencies → FastAPI project
- `django` in dependencies → Django project
- `asyncio` imports or `async def` → Async code
- `.python-version` or `uv.lock` → Uses uv package manager

**When Python detected:**

1. Use Skill tool to load `python:python-testing`
2. Use Skill tool to load `python:python-project`
3. Use patterns from loaded skills in plan tasks
4. Use `uv run` prefix for all Python commands

**When async/performance code detected:**

- Use Skill tool to load `python:python-performance`

**When FastAPI/Django detected:**

- Dispatch `python:python-expert` agent for framework-specific patterns

## Optional: Track Plan Writing Phases

For complex plans (5+ tasks), use TodoWrite to track progress:

- Research existing architecture
- Define high-level approach
- Break down into tasks
- Add code examples
- Generate diagrams (if applicable)
- Execution handoff

**Context:** This should be run in a dedicated worktree (created by brainstorming skill).

**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`

## Bite-Sized Task Granularity

**Each step is one action (2-5 minutes):**

- "Write the failing test" - step
- "Run it to make sure it fails" - step
- "Implement the minimal code to make the test pass" - step
- "Run the tests and make sure they pass" - step
- "Commit" - step

## Task Complexity Classification

Every task MUST include a complexity tag. This enables efficient execution.

| Complexity | Examples | TDD? | Code Review? |
|------------|----------|------|--------------|
| **TRIVIAL** | Delete file, rename, typo fix, config update | No | Parent verifies git diff |
| **SIMPLE** | Small refactor, single-file change, add comment | If code changes | Haiku (optional) |
| **MODERATE** | Feature implementation, bug fix with tests | Yes | Sonnet |
| **COMPLEX** | Multi-file feature, architectural change | Yes | Opus |

**Classification heuristics:**

- **TRIVIAL:** No new logic, no tests needed, <10 lines changed
- **SIMPLE:** Minor logic changes, one test file, <50 lines changed
- **MODERATE:** New functionality, multiple test cases, 50-200 lines
- **COMPLEX:** Multiple files, architectural decisions, >200 lines or high risk

## Plan Document Header

**Every plan MUST start with this header:**

```markdown
# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use workflow:executing-plans to implement this plan task-by-task.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

---
```

## Task Structure

```markdown
### Task N: [Component Name]

**Complexity:** [TRIVIAL | SIMPLE | MODERATE | COMPLEX]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

**Step 1: Write the failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

**Step 2: Run test to verify it fails**

Run: `uv run pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"

**Step 3: Write minimal implementation**

```python
def function(input):
    return expected
```

**Step 4: Run test to verify it passes**

Run: `uv run pytest tests/path/test.py::test_name -v`
Expected: PASS

**Step 5: Commit**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```

```

## Remember
- Exact file paths always
- Complete code in plan (not "add validation")
- Exact commands with expected output
- Reference relevant skills with @ syntax
- DRY, YAGNI, TDD, frequent commits

## Python-Specific Patterns

When Python detected, load patterns from the python plugin instead of duplicating them here.

**Step 1: Load relevant skill**

```

Use Skill tool: python:python-testing

```

**Step 2: Copy patterns into plan tasks**

- Fixtures from skill → conftest.py setup task
- Parameterized tests from skill → test task examples
- Mocking patterns from skill → integration test examples

**For async/performance code detected:**

```

Use Skill tool: python:python-performance

```

**For FastAPI/Django detected:**

```

Task tool (python:python-expert):
  prompt: "Provide [framework] test patterns for [feature]"

```

## Diagram Generation Phase

Diagrams help Claude understand complex plans during execution. They're not just for humans - they serve as a reference that helps Claude maintain context during multi-step implementations.

### Step 1: Ask About Diagrams

Use AskUserQuestion:

```

Question: "Should I generate diagrams to help with plan execution?"
Header: "Diagrams"
multiSelect: false
Options:

- Auto-detect: Let Claude decide what diagrams (if any) would help execution
- Task Dependencies: Show task o