writing-plans

name	writing-plans
preamble-tier	2
version	1.0.0
description	Write comprehensive implementation plans from specs or requirements. Use when you have a spec or requirements for a multi-step task, before touching code. Plans are bite-sized, TDD-first, with exact file paths and complete code in every step.
allowed-tools	["Bash","Read","Grep","Glob","Agent","Write","Edit","AskUserQuestion"]
announce-action	create the implementation plan

Preamble (run first)

# === RKstack Preamble (writing-plans) ===

# Read detection cache (written by session-start via rkstack detect)
if [ -f .rkstack/settings.json ]; then
  cat .rkstack/settings.json
else
  echo "WARNING: .rkstack/settings.json not found — detection cache missing"
fi

# Session-volatile checks (can change mid-session)
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
_HAS_CLAUDE_MD=$([ -f CLAUDE.md ] && echo "yes" || echo "no")
echo "BRANCH: $_BRANCH"
echo "CLAUDE_MD: $_HAS_CLAUDE_MD"

Use the detection cache and preamble output to adapt your behavior:

• TypeScript/JavaScript — see detection.flowType (web or default). If web: check React/Vue/Svelte patterns, responsive design, component architecture. If default: CLI tools, MCP servers, backend scripts.
• Python — backend/ML/scripts. Check PEP8 conventions, pytest for testing.
• Go — backend/infra. Check error handling patterns, go test.
• Rust — systems. Check ownership patterns, cargo test.
• Java/C# — enterprise. Check build tool (Maven/Gradle/.NET), framework conventions.
• Ruby — web/scripting. Check Gemfile, Rails conventions if present.
• Terraform/HCL — infrastructure as code. Plan before apply, extra caution with state.
• Ansible — configuration management. Check inventory, role conventions, vault usage.
• Docker/Compose — containerized. Check service dependencies, .env patterns.
• justfile — task runner present. Use just commands instead of raw shell.
• mise — tool version manager. Versions are pinned — don't suggest global installs.
• CLAUDE.md exists — read it for project-specific commands and conventions.
• Read detection.stack for what's in the project and detection.stats for scale (files, code, complexity).
• Read detection.repoMode for solo vs collaborative.
• Read detection.services for Supabase and other service integrations.

AskUserQuestion Format

ALWAYS follow this structure for every AskUserQuestion call:

1. Re-ground: State the project, the current branch (use the _BRANCH value from preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
2. Simplify: Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.
3. Recommend: RECOMMENDATION: Choose [X] because [one-line reason] — always prefer the complete option over shortcuts (see Completeness Principle). Include Completeness: X/10 for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work.
4. Options: Lettered options: A) ... B) ... C) ... — when an option involves effort, show both scales: (human: ~X / CC: ~Y)

Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.

Completeness Principle

AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with AI. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans.

Effort reference — always show both scales:

Task type	Human team	CC + AI	Compression
Boilerplate	2 days	15 min	~100x
Tests	1 day	15 min	~50x
Feature	1 week	30 min	~30x
Bug fix	4 hours	15 min	~20x

Include Completeness: X/10 for each option (10=all edge cases, 7=happy path, 3=shortcut).

Completion Status

When completing a skill workflow, report status using one of:

• DONE — All steps completed successfully. Evidence provided for each claim.
• DONE_WITH_CONCERNS — Completed, but with issues the user should know about. List each concern.
• BLOCKED — Cannot proceed. State what is blocking and what was tried.
• NEEDS_CONTEXT — Missing information required to continue. State exactly what you need.

Escalation

It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result."

Bad work is worse than no work. You will not be penalized for escalating.

• If you have attempted a task 3 times without success, STOP and escalate.
• If you are uncertain about a security-sensitive change, STOP and escalate.
• If the scope of work exceeds what you can verify, STOP and escalate.

Escalation format:

STATUS: BLOCKED | NEEDS_CONTEXT
REASON: [1-2 sentences]
ATTEMPTED: [what you tried]
RECOMMENDATION: [what the user should do next]

Writing Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for the 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 the 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 when available (use the using-git-worktrees skill to create one before starting).

Save Plans To

docs/rkstack/plans/YYYY-MM-DD-<feature-name>.md

• User preferences for plan location override this default
• If CLAUDE.md specifies a plan directory, use that instead

Scope Check

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

File Structure

Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

• Design units with clear boundaries and well-defined interfaces. Each file should have 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 should live together. Split by responsibility, not by technical layer.
• In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure — but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.

This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

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

Web project plan additions

If flowType is web (from detection cache) and a task involves UI:

1. Visual verification step. Every task that creates or modifies a visible component gets an explicit verification step at the end:

   • Ensure dev server is running (see skills/browse/dev-server-discovery.md)
   • $RKSTACK_BROWSE goto <dev-url>/<page>
   • $RKSTACK_BROWSE snapshot -i -a — check interactive elements are present and correct
   • $RKSTACK_BROWSE console — must be clean (no errors)
   • $RKSTACK_BROWSE responsive — check mobile, tablet, desktop

2. Design reference. If the spec includes a design reference (mockup, DESIGN.md section), include it in the task description so the implementer can compare their result against the intended design.

If flowType is not web, skip this section entirely.

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

> **For agentic workers:** Use subagent-driven-development (recommended) or executing-plans skill to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

---

Task Structure

### 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: `[test command from CLAUDE.md] 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: `[test command from CLAUDE.md] 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"
```

No Placeholders

Every step must contain the actual content an engineer needs. These are plan 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
• Generic commands like "run the tests" without the exact command and expected output

Platform-Agnostic Config

Never hardcode framework-specific commands, file patterns, or directory structures in the plan. Instead:

1. Read CLAUDE.md of the target project for test commands, build commands, lint commands
2. If missing, use AskUserQuestion — let the user tell you the right command
3. Record the answer in the plan header so every task can reference it

Example: don't write pytest tests/ — read CLAUDE.md to find whether the project uses pytest, vitest, bun test, cargo test, or something else. Put the discovered command in the header and reference it in every task.

Ask Codex: second opinion on a plan-level decision

When you call AskUserQuestion to decide a substantive plan question (task decomposition strategy, test harness choice, which library to pin, rollout order, risky migration sequencing), include Ask Codex as an extra option. Skip it on trivial choices (a lint command name, a file-path convention).

If the user picks Ask Codex:

1. Assemble the consult prompt (XML blocks)

• <role> — Codex is a senior design consultant. Claude is writing an implementation plan and hit a decision point. The user picked "Ask Codex".
• <task> — Codex reads the question, your original options with rationale, the spec being implemented, and any constraints from the plan-so-far. Endorses/rejects each option and proposes new ones if warranted. One top recommendation.
• <question> — your question verbatim.
• <claude_options> — each original option with your one-line rationale.
• <context> — the linked spec (read it, include the relevant parts), the plan header (test command, build command from CLAUDE.md), any tasks already written that constrain this decision, the repo state from the preamble. Terse but concrete.
• <grounding_rules> — "Do not invent constraints. If a claim depends on an inference, say so."
• <structured_output_contract> — "Return only valid JSON matching the provided schema. Terse decision-quality rationales — shown to the user inline."

2. Call Codex

CONSULT=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/codex/consult.mjs" \
  --cwd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" \
  --effort medium \
  <<'CODEX_PROMPT'
<the assembled prompt>
CODEX_PROMPT
) ; EXIT=$?

Use timeout: 300000 (5 min). Exit codes: 0 ok, 1 Codex/parse failure, 2 usage error, 3 Codex CLI missing (tell the user to run !codex login).

3. Parse the JSON (schema: scripts/codex/consult-schema.json)

{
  "analysis": "...",
  "endorsed_existing": [{"label": "...", "rationale": "..."}],
  "rejected_existing": [{"label": "...", "reason": "..."}],
  "new_options":       [{"label": "...", "description": "...", "rationale": "..."}],
  "recommendation":     {"label": "...", "reason": "..."},
  "open_questions":    ["..."]
}

4. Re-present AskUserQuestion with Codex's input merged in

• One-sentence lead summarizing Codex's analysis.
• Every original option with Codex: <rationale> appended when endorsed, Codex ✗ <reason> when rejected.
• Every new option Codex proposed, labeled (Codex).
• Mark the recommended label (Recommended by Codex).
• open_questions as a short footer if any.

Do NOT offer Ask Codex again on the same question.

Self-Review

After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.

1. Spec coverage: Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.

2. Placeholder scan: Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.

3. Type consistency: Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called clearLayers() in Task 3 but clearFullLayers() in Task 7 is a bug.

4. Completeness audit: For each task, rate its completeness on a 1-10 scale using the Completeness Principle from the preamble:

• 10/10 — All edge cases handled, full error paths, complete test coverage
• 7/10 — Happy path solid, but some edge cases or error handling deferred
• 3/10 — Shortcut that defers significant work to "later"

Flag any task below 7/10. For each flagged task, decide: is the missing work a "lake" (achievable in minutes with AI) or an "ocean" (multi-quarter effort)? If it's a lake — expand the task now. Don't recommend shortcuts when the complete implementation is cheap.

If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.

After self-review, invoke the dual-review skill on the plan file. This runs a Codex review loop: Codex reviews the plan against its linked spec in read-only mode, you evaluate each finding, fix valid ones, and loop until clean or max 3 rounds are reached. This step is automatic — do not skip it or ask the user whether to run it.

Execution Handoff

After saving the plan, offer execution choice:

"Plan complete and saved to docs/rkstack/plans/<filename>.md. Two execution options:

1. Subagent-Driven (recommended) — I dispatch a fresh subagent per task, review between tasks, fast iteration

2. Inline Execution — Execute tasks in this session using executing-plans, batch execution with checkpoints

Which approach?"

If Subagent-Driven chosen:

• Use subagent-driven-development skill
• Fresh subagent per task + two-stage review

If Inline Execution chosen:

• Use executing-plans skill
• Batch execution with checkpoints for review

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
• Read CLAUDE.md of the target project before writing any commands
• Apply humanizer constraints for the plan header prose (Goal, Architecture) — humans review this document