writing-plans

name	writing-plans
description	Use when you have an approved design (design.md) for a multi-step task — produces the fused technical spec.md + tasks.md, before touching code.

Writing Plans

Overview

Turn the approved design (design.md) into the fused technical spec.md (architecture, file structure, phase ordering, numbered acceptance criteria) plus the tasks.md breakdown (bite-sized tasks, each naming the AC-N it satisfies and whether it is delegable). Assume the implementing engineer has zero context for our codebase and questionable taste: document which files to touch for each task, the code, the docs they might need, and how to test it. 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 write the technical spec and tasks."

Context: This runs after brainstorming wrote design.md and the branch/mode were recorded. Work in the spec's branch.

Save to: .memex/specs/YYYY-MM-DD-<slug>/spec.md (the technical spec) and tasks.md, alongside the design.md brainstorming wrote.

• (User preferences for location override this default)
• Wikilinks are path-qualified — the dated folder is the discriminator, since filenames are bare. In spec.md/tasks.md frontmatter and body, write sibling links with the folder prefix and a display alias: [[YYYY-MM-DD-<slug>/design|design]] and [[YYYY-MM-DD-<slug>/spec|spec]] (not bare [[spec]], which is ambiguous across specs).

Scope Check

If the design covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest splitting — one spec per subsystem. Each spec should produce working, testable software on its own.

Writing the technical spec (spec.md)

Copy .memex/specs/_template/spec.md into the spec folder and fill it from the approved design.md:

• Frontmatter — set status: draft, feature, created, the recorded branch:/mode:, and scope: — your honest sizing of the work, one of low | medium | high | complex. scope is recorded only; nothing branches on it yet (reserved for a future quick-mode).
• Architecture / File Structure / Phase Ordering — the technical how. Before defining tasks, map out which files will be created or modified and what each is responsible for. This is where decomposition decisions get locked in.
  • Design units with clear boundaries and well-defined interfaces. Each file has one clear responsibility.
  • You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
  • Files that change together live together. Split by responsibility, not by technical layer.
  • In existing codebases, follow established patterns. Don't unilaterally restructure — but a split of an unwieldy file you're modifying is reasonable.
• Acceptance Criteria — number each AC-1, AC-2, …. Each must be binary, observable, verifiable in under a minute, and free of vague verbs ("works", "fast"/"robust" without a number, "gracefully"). These IDs are the contract tasks.md and memex-code-review trace against, so they must be specific enough to check.
• The non-technical why (purpose, motivation, definitions, non-goals) stays in design.md — don't duplicate it here.

Bite-Sized Task Granularity (tasks.md)

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

Tasks Document Header

Every tasks.md MUST start with this header:

# [Feature Name] — Tasks

> **For agentic workers:** implement task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. Each task names the `AC:` it satisfies and a `Delegable:` note.

**For this spec:** `[[YYYY-MM-DD-<slug>/spec|spec]]`

---

Task Structure

### Task N: [Component Name]

**AC:** [AC-N it satisfies, e.g. AC-1, AC-3]
**Delegable:** [yes/no + one-line isolated context an isolated subagent would receive]
**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"
```

Every AC-N defined in spec.md must be named by at least one task's AC: field — that is the traceability contract the validator and code-review enforce.

No Placeholders

Every step must contain the actual content an engineer needs. These are task failures — never write them:

• "TBD", "TODO", "implement later", "fill in details"
• "Add appropriate error handling" / "add validation" / "handle edge cases"
• "Write tests for the above" (without actual test code)
• "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
• Steps that describe what to do without showing how (code blocks required for code steps)
• References to types, functions, or methods not defined in any task

Remember

• Exact file paths always
• Complete code in every step — if a step changes code, show the code
• Exact commands with expected output
• DRY, YAGNI, TDD, frequent commits

Self-review the spec — both modes, no human gate

After spec.md + tasks.md are written, review them before implementation. This runs in both autonomous and reviewed. The user is not asked to review — design approval already gated the work.

Author pass (inline, you):

1. Spec coverage — skim each requirement in design.md and each spec section. Can you point to a task that implements it? List and close any gaps.
2. AC coverage — every AC-N in spec.md is referenced by at least one task's AC: field, and no task cites an AC-N that does not exist.
3. Placeholder scan — no {{}}, "TBD", "TODO", or "No Placeholders"-list red flags survive.
4. Type consistency — types, method signatures, and property names match across tasks (a clearLayers() in Task 3 but clearFullLayers() in Task 7 is a bug).

Fix issues inline.

Gates (run in order):

1. Mechanical — run .memex/scripts/validate-spec.sh <spec-folder>; a non-zero exit names a structural defect (missing frontmatter key, surviving {{placeholder}}, vague-verb AC, or an AC-N no task references). Fix and re-run until it exits 0.
2. Spec-document-reviewer subagent — dispatch it (see spec-document-reviewer-prompt.md) over spec.md + tasks.md. If Issues Found: fix, re-dispatch, repeat until Approved (max 3 iterations, then surface to human).
3. /memex:review-spec — the external evaluator (constitution + vault compliance, vague ACs, duplication). Fix any FAIL.

Execution Handoff

After the spec self-review passes, follow the AGENTS.md ### Spec flow tail:

• handoff = yes (either mode) → print a ```txt handoff prompt (a one-paragraph summary + the paths to design/spec/tasks + the mode) and stop. The user runs /compact (or opens a new chat) and pastes it to resume. Never hand off before the artifacts exist.
• handoff = no → implement. Decide the execution approach yourself based on task count and complexity — do not ask the user to choose:
  • Subagent-Driven (large, 5+ tasks, many files, complex migrations): dispatch a fresh subagent per task, review between tasks. REQUIRED SUB-SKILL: superpowers:subagent-driven-development
  • Inline Execution (small, < 5 tasks, focused changes): execute tasks in this session with checkpoints. REQUIRED SUB-SKILL: superpowers:executing-plans
  • Announce which approach you chose and start immediately.
• Delivery (after implement → quality gate → reflect): autonomous opens the PR (/memex:new-pr) and runs the memex:code-review cycle to lgtm on its own; reviewed first asks "open the PR and run code-review?", then does the same.