Initial commit

skills/writing-plans/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: writing-plans
+description: Use when design is complete and you need detailed implementation tasks for engineers with zero codebase context - creates comprehensive implementation plans with exact file paths, complete code examples, and verification steps assuming engineer has minimal domain knowledge
+---
+
+# Writing Plans
+
+## 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."
+
+**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
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers: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]
+
+**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: `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: `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
+
+## Execution Handoff
+
+After saving the plan, present execution options:
+
+```
+Plan complete and saved to `docs/plans/${filename}.md`.
+
+## Recommended Next Step: /cc:parse-plan
+
+Decompose this plan into parallel task files. This enables:
+- Up to 2 tasks executing concurrently per batch
+- ~40% faster execution for parallelizable plans
+- 90% context reduction per task
+
+**Best for:** Plans with 4+ tasks
+
+## Alternative: Execute Without Decomposition
+
+Use sequential execution via subagent-driven-development.
+- Best for simple plans (1-3 tasks)
+- Simpler flow, no decomposition overhead
+- One task at a time
+
+## Important
+
+Decomposition is **REQUIRED** for parallel execution.
+Always decompose plans with 4+ tasks to enable parallel-subagent-driven-development.
+
+---
+
+Which approach?
+A) Decompose plan (/cc:parse-plan) - Recommended
+B) Execute sequentially without decomposition
+C) Exit (run manually later)
+```
+
+**If user chooses A:**
+- Invoke `decomposing-plans` skill
+- Proceed with decomposition workflow
+
+**If user chooses B:**
+- Invoke `subagent-driven-development` skill
+- Execute tasks sequentially from monolithic plan
+
+**If user chooses C:**
+- Exit workflow
+- User can run `/cc:parse-plan` or execution commands later