plan

/plan

You are creating a technical plan: Define HOW to build what the spec describes.

The plan is the technical layer. This is where the developer's expertise matters most — not in writing the code, but in making the architectural decisions. The plan transforms the abstract spec into a concrete, bounded implementation guide.

---

Input

You need the functional spec from /spec. If it is not in context:

$ARGUMENTS

If $ARGUMENTS is empty and no spec is in context, ask the user to paste the spec before continuing.

---

Step 0 — Consult the wiki

Before reading the codebase, check the repo-scoped wiki for prior plans on related topics. A past plan may already describe the technical approach — reusing it avoids rediscovering architecture decisions.

bash "${CLAUDE_PLUGIN_ROOT}/skills/wiki-ingest/scripts/wiki-query.sh" <keywords from the spec>

Extract 3-6 meaningful keywords from the spec in context (feature name, major components, domain terms). Run the query:

• Exit 0 (matches found): present the top 3 matches to the user and ask:

  "Found related plans in .wiki/. Reuse one, extend one, or ignore and write a fresh plan?" If the user chooses to reuse or extend, read the selected page(s) and use them as prior-art context when reading the codebase in Step 1.

• Exit 1 (no matches): continue silently to Step 1.
• Exit 2 (no .wiki/): continue silently to Step 1. Absence of a wiki is not an error.

Do not block the flow. If the query script is missing or errors, continue with Step 1 — the wiki is optional context, not a hard dependency.

---

Step 1 — Read the codebase

Before writing the plan, understand the existing codebase:

1. Project structure: Read the directory layout, configuration files, and entry points
2. Existing patterns: How is similar functionality already implemented? Follow those patterns.
3. Conventions: Naming, file organization, testing approach, error handling patterns
4. Dependencies: What libraries, frameworks, and tools are already in use?
5. Architecture: What layers exist? How does data flow? Where does new code belong?

Do not guess. Read the files. The plan must be coherent with what already exists.

---

Step 2 — Write the technical plan

Output the following structure:

---

Technical Plan

Feature: [from spec] Date: [today's date]

Architecture Decisions

Numbered list of the significant design choices and their rationale. Each decision should reference existing patterns in the codebase when applicable.

1. Decision: [what] — Rationale: [why] — Reference: [existing pattern or file if applicable]

Affected Components

List every file, module, service, or layer that will be created or modified.

• path/to/component — what changes and why

Data Models / Contracts

If the feature involves data:

• New entities, types, or schemas (describe fields and constraints)
• API contracts (request/response shapes)
• State changes (what data is created, read, updated, deleted)

Keep descriptions structural — field names and types, not code.

Testing Strategy

Define what must be tested and how:

• Unit tests: What logic to test in isolation
• Integration tests: What interactions to test end-to-end
• Edge case tests: Derived directly from the spec's acceptance criteria
• What NOT to test: Explicitly exclude trivial or framework-provided behavior

Technical Constraints

• Performance requirements (if any)
• Security considerations (auth, input validation, data exposure)
• Compatibility constraints (API versioning, backward compatibility)
• Infrastructure requirements (if any)

Risks / Unknowns

• Technical risk or unknown 1
• Technical risk or unknown 2

---

Gotchas

These are common failure modes when writing plans. Watch for them:

• Inventing new patterns. Claude loves to introduce new abstractions, design patterns, or folder structures. If the codebase already has a pattern for similar functionality, follow it — even if you think yours is "better." New patterns add cognitive load and inconsistency.
• Not actually reading the codebase. Claude sometimes writes a plausible-sounding plan based on general knowledge instead of reading the actual files. If a decision isn't grounded in a specific file or pattern you read, it's a guess.
• Proposing libraries not in the project. Check package.json, *.csproj, go.mod, Cargo.toml, etc. before suggesting a new dependency. If the project already has a library that does the job, use it.
• Duplicating the spec. The plan should not restate functional requirements. If you find yourself writing "The system shall...", you're writing spec, not plan. Focus on HOW, not WHAT.
• Vague component descriptions. "Add a new service for handling payments" is useless. "Create src/services/payment-processor.ts following the pattern in src/services/order-processor.ts, implementing the PaymentService interface" gives the agent something to work with.
• Over-architecting for a single feature. If the spec describes one feature, the plan should not introduce a generic framework that "could support future features." Build what's needed now.

---

Important constraints

• Ground decisions in the codebase. Every architectural decision should reference existing patterns. If you're introducing something new, explain why.
• Don't over-architect. The plan should describe the minimum viable approach. No premature abstractions, no "just in case" features.
• Don't repeat the spec. The plan assumes the reader has the spec. Focus on technical decisions, not functional descriptions.
• Be specific about locations. "Add a new service" is too vague. "Create src/services/payment-processor.ts following the pattern in src/services/order-processor.ts" is useful.
• Reference existing conventions. If the project uses a specific testing library, pattern, or folder structure, name it.
• Use extended thinking for complex decisions. When the architecture involves trade-offs between multiple valid approaches, use high-effort reasoning to evaluate each option before committing.

---

Next step

After the plan is reviewed and approved, run:

/tasks

The spec + plan become the input for task breakdown.