dotfiles/.config/opencode/skills/writing-plans/SKILL.md

name, description, permalink

name	description	permalink
writing-plans	Create implementation plans detailed enough for an executor with little project context	opencode-config/skills/writing-plans/skill

Writing Plans

When to Use

Use this skill when you have requirements for a non-trivial implementation and need a clear plan before editing code.

Core Goal

Write a comprehensive implementation plan that assumes the executor lacks prior context. The plan must include exact tasks, file paths, expected code shape, and verification commands.

Scope Check

If requirements contain multiple independent features/subsystems, split into separate plans so each can be implemented and verified independently.

Plan Storage (basic-memory)

Store plans as basic-memory notes in the repo project under plans/.

• Project: opencode-config (or current repo project)
• Note path: plans/<feature-or-workstream-name>
• Use only basic-memory plans/ notes for plan storage.

Plan Header Template

# [Feature Name] Implementation Plan

> For implementation: use `subagent-driven-development` when subagents are available; otherwise use `executing-plans`.

**Goal:** [one sentence]

**Architecture:** [2-3 concise sentences]

**Tech Stack:** [languages, frameworks, tools]

Build the Plan in This Order

1. Map file structure first

   • List files to create/modify/test using exact paths.
   • State each file's responsibility.
   • Prefer small, focused files and clear interfaces.

2. Decompose into small actionable tasks

   • Tasks should be independently understandable and testable.
   • Use checkbox syntax for steps: - [ ].
   • Keep each step concrete (write test, run command, implement minimal code, re-run checks).

3. Include code shape guidance

   • Show function/class signatures, data flow, and key logic constraints.
   • Avoid vague instructions like "add validation" without describing expected behavior.

4. Include exact verification commands (when known)

   • Provide commands with scope and expected result.
   • Example: pytest tests/path/test_file.py::test_case -v → expected FAIL before implementation, PASS after.
   • If exact commands are unknown, state how to discover them from repo scripts/docs.

Task Template

### Task N: [Name]

**Files:**
- Create: `path/to/new_file.ts`
- Modify: `path/to/existing_file.ts`
- Test: `path/to/test_file.ts`

- [ ] Step 1: Write/extend failing test for [specific behavior]
- [ ] Step 2: Run: `<exact command>` and confirm expected failure
- [ ] Step 3: Implement minimal code for [specific behavior]
- [ ] Step 4: Run: `<exact command>` and confirm pass
- [ ] Step 5: Run broader verification: `<exact command>`

Plan Review Loop (required)

After each plan chunk:

1. Review for completeness, scope alignment, actionable decomposition, and verification quality.
2. Fix identified issues in the same chunk.
3. Re-review until the chunk is implementation-ready.

Suggested chunking: use ## Chunk N: <name> headings for large plans.

Completion Handoff

When done, state where the plan is stored in basic-memory (for example plans/<name>) and whether execution should proceed via:

• subagent-driven-development (preferred when available), or
• executing-plans (single-agent execution).