JS Feature Planner

JS Feature Planner

Why this exists

Planning and implementation are different jobs. Mixing them means ambiguity gets discovered halfway through writing code, which is the most expensive place to discover it. This skill's only job is to produce a plan precise enough that a separate skill (senior-js-developer) can write tests and code directly against it without needing to re-interpret intent along the way.

The output of this skill is a contract, not a summary. senior-js-developer will take the Test Scenarios and Implementation Sequence sections literally — vague entries there produce vague tests and code downstream. Precision here saves rework later.

Workflow

1. Gather input

Ask the user to paste the user story and the issue description (or just whichever one is available — a well-written issue can be sufficient on its own).

2. Scan the existing codebase

Before drafting anything, check for CLAUDE.md and look at an existing comparable module (e.g. template/ in a repository-pattern NestJS project) so the plan reflects real conventions — actual folder placement, actual patterns already in use — rather than generic assumptions.

3. Resolve ambiguity

Identify real gaps: missing acceptance criteria, unclear edge-case behavior, undefined error handling, unspecified data shapes.

• Ask one focused question at a time, with a proposed default where you can ("Should this return 404 or an empty array when nothing matches? I'd default to 404 to match template.controller.ts.") — this is faster for the user to confirm than to answer an open-ended question.
• If the input is already unambiguous and small, skip straight to drafting — don't manufacture questions for the sake of process.

4. Draft the plan

Use the exact structure below. Every section should be concrete enough that someone with no other context could implement from it.

# Plan: <short title>

## Goal

One or two sentences: what this change accomplishes and why.

## Acceptance Criteria

- Specific, testable statements of what "done" means.

## Edge Cases

- Each edge case named explicitly, with the expected behavior stated (not just "handle errors" — state what should happen).

## Out of Scope

- What this change deliberately does NOT do, to prevent scope creep during implementation.

## Technical Approach

### Files to create/modify

- `path/to/file.ts` — one line on what changes and why.

### Data / Schema Changes

- Prisma schema changes, migrations needed, or "None."

### API / Interface Contract

- For HTTP endpoints: method, route, request DTO shape, response DTO shape, status codes for each outcome (success and each error case).
- For non-HTTP features: function/method signatures, inputs, outputs, thrown errors.

### Implementation Sequence

1. Ordered, concrete steps (e.g. "Add `findByEmail` to `UserRepositoryInterface` and `UserRepository`" before "Use it in `UserService.checkDuplicate`"). This should be sequenced so each step is implementable and, ideally, testable on its own.

### Test Scenarios

- One line per test, phrased as the test itself would read (e.g. "returns 404 when template ID does not exist," "throws BadRequestException when name exceeds 255 characters"). Cover: the happy path, every edge case listed above, and every error condition in the API contract. This list is what `senior-js-developer` will write tests against directly — don't leave a scenario implied without stating it.

## Assumptions / Open Questions

- Anything you weren't able to fully resolve, stated explicitly rather than silently decided.

5. Present the plan — CHECKPOINT

Show the full plan and stop. Do not proceed to save/finalize until the user explicitly approves. If they request changes, revise and re-present.

6. Save and hand off

Once approved, save the plan as a file: plans/<feature-slug>-plan.md (create the plans/ directory if it doesn't exist). Tell the user the plan is ready and can be handed directly to the senior-js-developer skill to begin test writing.

Trivial-task judgment

For a genuinely tiny, unambiguous change (a one-line config fix, an obvious typo), a full plan with every section filled out may be overkill. It's fine to produce an abbreviated plan (Goal, one Test Scenario, skip the rest) — but still produce something in the same structure, since senior-js-developer expects a plan to exist. Use judgment; don't force ceremony onto trivial work, but don't skip the handoff contract either.