writing-plans
Use when an approved design or complete requirements need a multi-step implementation plan, before touching code
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- writing-plans
- description
- Use when an approved design or complete requirements need a multi-step implementation plan, before touching code
03 SKILL.md 正文
Writing Plans
Overview
Turn an approved design into a complete implementation plan. Assume the implementer is skilled but has no prior context for the repository or problem. Give them exact paths, interfaces, code, checks, expected results, and small tasks. Use DRY, YAGNI, test-driven development, and frequent commits.
Input: An approved design document or complete requirements.
Save plans to: docs/plans/YYYY-MM-DD-<feature-name>.md
User instructions for the plan location override this default.
Scope Check
If the design covers independent subsystems, propose separate plans. Each plan must produce
working, testable software on its own. Do not hide unresolved design choices inside an
implementation task. Return unresolved choices to brainstorming.
Map Files and Interfaces First
Before defining tasks, map every file to create, modify, test, or delete. State what each file owns. Follow repository patterns. Keep units focused and give every boundary an explicit interface.
For each task, state:
- What it consumes from earlier tasks, with exact names and signatures.
- What it produces for later tasks, with exact names and types.
- Which runnable check proves the task is complete.
Task Size
A task is the smallest unit with its own test cycle and useful review gate. Fold setup, configuration, documentation, and scaffolding into the task whose deliverable needs them. Split tasks only when a reviewer could accept one and reject the other.
Each checklist step is one action. Use this order for behavior changes:
- Write the failing test.
- Run it and record the expected failure.
- Write the minimal implementation.
- Run the focused test and record the expected pass.
- Run the wider relevant check.
- Commit the verified task.
Plan Header
Every plan starts with this structure:
# [Feature Name] Implementation Plan
> **For agentic workers:** Implement this plan task by task. Use checkbox
> (`- [ ]`) syntax for tracking. Run each task's checks before starting the next task.
**Goal:** [One sentence describing the completed behavior]
**Architecture:** [Two or three sentences describing the approach and boundaries]
**Tech Stack:** [Languages, frameworks, and tools verified in the repository]
## Global Constraints
[Copy each project-wide requirement from the approved design with its exact value.]
---
Task Structure
Use this structure for every task:
### Task N: [Testable Deliverable]
**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:line`
- Test: `tests/exact/path/to/test.py`
**Interfaces:**
- Consumes: [exact names, signatures, and types from earlier tasks]
- Produces: [exact names, signatures, and types later tasks use]
- [ ] **Step 1: Write the failing test**
```python
def test_specific_behavior():
result = function(input_value)
assert result == expected_value
```
- [ ] **Step 2: Run the test and verify RED**
Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: FAIL because `function` does not implement the required behavior.
- [ ] **Step 3: Write the minimal implementation**
```python
def function(input_value):
return expected_value
```
- [ ] **Step 4: Run the focused test and verify GREEN**
Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: PASS.
- [ ] **Step 5: Run the wider relevant check**
Run: `[exact repository test, lint, or build command]`
Expected: `[exact success marker or pass summary]`.
- [ ] **Step 6: Commit**
```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific behavior"
```
Use real code from the approved design and repository. The sample above defines structure, not content to copy unchanged.
No Placeholders
Every task must contain what the implementer needs. A plan is incomplete if it contains:
TBD,TODO, "implement later", or "fill in details".- "Add validation", "handle errors", or "write tests" without exact behavior and code.
- "Similar to Task N" instead of repeated context needed by that task.
- A code-changing step without the relevant code.
- A function, type, flag, command, or path not verified in the repository or defined by the plan.
Self-Review
After writing the plan, review it against the approved design:
- Map every design requirement to a task. Add any missing task.
- Search for placeholders and vague steps. Replace them with exact content.
- Check that names, signatures, and types match across tasks.
- Check that each command exists and each expected result is specific.
- Check that every task ends in a runnable verification and a commit.
Fix findings in the plan before handoff.
Execution Handoff
After saving the plan, inspect what execution methods the current host and repository actually provide. Offer only available choices, in this order:
- Repository subagent workflow: Use the repository's documented subagent process when it exists. Dispatch one task at a time and review between tasks.
- Current session: Execute small checked batches here. Stop at the review checkpoints in the plan.
- Fresh implementation session: Start a new session with the saved plan and implement it task by task.
Name the saved docs/plans/<filename>.md path in the handoff. Do not require an execution skill
or command that is absent from the current host.
When the plan will be handed to a fresh session, run /align-prompt fable-plan <path> before writing the handoff.
04 同仓库更多 Skills
verify-loam
Prove a Loam change in a real rendered project: copier-render this checkout, then drive headless and interactive Claude Code sessions, stubbed Codex runs and copier updates in the render and capture hook, memory, deny-rule, update and check evidence. Use before shipping any seed, hook, settings or copier.yml change.
hypothesis-tree
Persistent hypothesis tree for multi-step, multi-session investigations. Use when a "why does X fail" question branches into sub-hypotheses that must survive across sessions, or when falsifiable claims need tracking with dated, linked evidence. Maintains one markdown file with add, update, review, and prune subcommands, each gated on verifying the cited evidence file exists and supports the claim. NOT for a single-session bug hunt, a one-command question, or general note-taking.
fable-prompting
Which Claude Fable 5.2 guide sections you can act on from a session, and which Claude Code already injects. Use before writing a Fable session prompt or brief.
catchup
Read-only session bootstrap briefing of git state, commits, handoff, tasks and red flags. Use when resuming work, starting a fresh session, or unsure of project state.
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
wizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.