MalinandClaude Sonnet 5
c7ce105e00
Evaluated obra/superpowers and JuliusBrussee/caveman for gaps in the existing library. These three fill real ones (plan-to-delegate handoff, evidence-based review triage, completion vs. integration authority); adapted for this fleet's Gitea/RLS/multi-delegate conventions. Everything else in both repos duplicated existing skills or didn't fit (see README Provenance note on caveman). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
114 lines
4.4 KiB
Markdown
114 lines
4.4 KiB
Markdown
---
|
|
name: writing-implementation-plans
|
|
description: Use when requirements are settled and a multi-step change needs an implementation plan that memoryless delegates can execute without access to the originating conversation.
|
|
license: MIT
|
|
source: https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md
|
|
---
|
|
|
|
# Writing Implementation Plans
|
|
|
|
A plan is an executable handoff, not a summary of intent. The worker may be a
|
|
fresh CLI delegate with no conversation history, and individual tasks may be
|
|
assigned out of order. If the plan leaves a choice implicit, the worker will
|
|
have to invent it.
|
|
|
|
## Before writing tasks
|
|
|
|
1. Read the settled spec or requirements and inspect the actual code paths,
|
|
tests, project instructions, and established patterns involved.
|
|
2. Resolve contradictions and material unknowns before planning. Marking them
|
|
`TBD` only moves the design decision to a less-informed delegate.
|
|
3. Map every file to create or modify and give each one a clear
|
|
responsibility. Avoid unrelated restructuring.
|
|
4. Split work into independently testable vertical slices. Fold setup,
|
|
migrations, wiring, and documentation into the slice that needs them;
|
|
don't create standalone tasks that leave the system unusable.
|
|
5. Identify shared files and state. Tasks that edit the same bootstrap file,
|
|
schema, migration sequence, or live environment are sequential unless the
|
|
design removes that collision. See `parallel-delegate-shared-files`.
|
|
|
|
## Plan header
|
|
|
|
Start with:
|
|
|
|
```markdown
|
|
# <Feature> Implementation Plan
|
|
|
|
**Goal:** <one sentence>
|
|
|
|
**Architecture:** <two or three sentences describing the approach and boundaries>
|
|
|
|
**Stack and environment:** <relevant runtimes, services, jail/container, database>
|
|
|
|
## Global constraints
|
|
|
|
- <exact version, naming, compatibility, security, tenant-isolation, and scope rules>
|
|
|
|
## Verification
|
|
|
|
- <commands for targeted tests, full regression tests, and any real end-to-end check>
|
|
```
|
|
|
|
Copy exact values from the requirements. For multi-tenant work, state the
|
|
tenant/RLS invariants explicitly; never let a worker infer them from nearby
|
|
code. For remote or production-adjacent work, state the exact host/jail,
|
|
whether mutation is authorised, and how secrets must be read without being
|
|
printed.
|
|
|
|
## Task contract
|
|
|
|
Each task must stand alone:
|
|
|
|
```markdown
|
|
### Task N: <independently testable outcome>
|
|
|
|
**Depends on:** <prior task outputs, or "none">
|
|
|
|
**Files:**
|
|
- Create: `exact/path`
|
|
- Modify: `exact/path` — <symbol or section>
|
|
- Test: `exact/path`
|
|
|
|
**Interfaces:**
|
|
- Consumes: <exact names, signatures, schemas, or artifacts>
|
|
- Produces: <exact names, signatures, schemas, or artifacts>
|
|
|
|
**Requirements:**
|
|
- <observable behavior and edge cases>
|
|
|
|
**Steps:**
|
|
- [ ] Write the failing test for <behavior>.
|
|
- [ ] Run `<targeted command>`; expect <specific failure proving the test is red-capable>.
|
|
- [ ] Implement the smallest change that passes it.
|
|
- [ ] Run `<targeted command>`; expect <specific success>.
|
|
- [ ] Run `<broader command>`; expect no regressions.
|
|
- [ ] Commit only this task's files with `<message or project convention>`.
|
|
|
|
**Report:** <facts and evidence the delegate must return>
|
|
```
|
|
|
|
Write exact commands and concrete expected signals. Include code or
|
|
pseudocode only where it removes a real ambiguity; don't turn the plan into a
|
|
second implementation. When a task brief will be extracted from the plan,
|
|
repeat its binding constraints instead of saying “same as above.”
|
|
|
|
## Self-review before delegation
|
|
|
|
- Trace every requirement to a task and every task to the goal. Remove gaps
|
|
and scope creep.
|
|
- Search for placeholders and vague steps: `TBD`, `TODO`, “handle errors,”
|
|
“add validation,” “write tests,” “similar to Task N.” Replace each with an
|
|
explicit decision or action.
|
|
- Check that interface names and types match across tasks.
|
|
- Check ordering: a task must not consume an artifact that does not exist yet.
|
|
- Check concurrency: no parallel tasks may edit the same file or mutate the
|
|
same shared environment.
|
|
- Check verification: every claimed outcome has a command or observation that
|
|
could prove it false.
|
|
- Have the user approve material architectural or scope decisions before
|
|
implementation begins.
|
|
|
|
When dispatching tasks, still apply `delegate-brief-writing`: the extracted
|
|
task plus relevant global constraints, confirmed facts, credentials handling,
|
|
verification, and report contract form the self-contained brief.
|