add-planning

name	add-planning
description	Create/update plan.md with sequenced tasks, file mapping, dependencies and S/M/L estimates

Technical Planning

Skill for creating technical implementation plans. Creates/updates plan.md with tasks, file mapping and estimates.

Principle: Concrete, executable plan — not a wishlist.

---

When to Use

• Feature documented and ready for dev → create plan.md
• plan.md exists but incomplete → fill missing tasks
• Scope changed → update affected tasks
• During dev, discovered more work → add tasks

When NOT to Use

• Without about.md (document the feature first)
• Without discovery.md (run feature discovery first)
• Non-technical roadmaps or product timelines (use product docs instead)

---

Workflow

Phase 1: Load Context

# Read feature documentation
cat docs/features/[FEATURE_ID]/about.md
cat docs/features/[FEATURE_ID]/discovery.md
cat docs/features/[FEATURE_ID]/design.md  # if it exists

Extract:

• Requirements (RF/RNF/RN) from about.md
• Files to create/modify from discovery.md
• UI components from design.md (if any)

Phase 2: Structure Tasks

Breakdown rules:

Size	Criteria	Action
Simple	1–3 files, no deps	Single task
Medium	4–10 files, sequential deps	Tasks per layer
Large	>10 files, multiple domains	Separate batches

Default order (bottom-up):

1. Domain (entities, enums, types)
2. Database (migrations, repositories)
3. Business (services, use-cases)
4. API (controllers, DTOs, validators)
5. Frontend (components, hooks, stores)
6. Integration (tests, e2e)

Phase 3: Estimate Complexity

Scale:

S = Small  → 1-2 files, localized change
M = Medium → 3-5 files, moderate logic
L = Large  → 6+ files, complex logic

Complexity signals:

• New entities → +1 size
• Migrations → +1 size
• External integrations → +1 size
• Complex UI (forms, tables) → +1 size

Phase 4: Structure Document

Template plan.md (Technical Style):

# Plan: [Feature Name]

Technical plan for implementing [feature]. Based on about.md and discovery.md.

---

## Spec

### Context
{"feature":"[ID]","branch":"feature/[ID]-[name]","deps":["package@version"],"estimate":"[S/M/L]"}

### Files
{"create":["path/file1.ts","path/file2.ts"],"modify":["path/existing.ts"]}

### Tasks
[{"id":1,"task":"Create entity [Name]","estimate":"S","deps":[]},{"id":2,"task":"Create migration","estimate":"S","deps":[1]},{"id":3,"task":"Create repository","estimate":"S","deps":[2]},{"id":4,"task":"Create service","estimate":"M","deps":[3]},{"id":5,"task":"Create controller + DTOs","estimate":"M","deps":[4]},{"id":6,"task":"Create UI components","estimate":"M","deps":[5]},{"id":7,"task":"e2e tests","estimate":"S","deps":[6]}]

---

## Detailed Tasks

### Task 1: Create entity [Name]
**Estimate:** S
**Files:** `libs/domain/src/entities/[Name].ts`
**Deps:** None

**Checklist:**
- [ ] Fields per about.md
- [ ] Enums if needed
- [ ] Export in index.ts

---

### Task 2: Create migration
**Estimate:** S
**Files:** `libs/app-database/src/migrations/[timestamp]-[name].ts`
**Deps:** Task 1

**Checklist:**
- [ ] Table with fields
- [ ] Required indexes
- [ ] Foreign keys

---

[... continue for each task ...]

---

## Batching (if applicable)

**Batch 1: Foundation**
- Tasks 1-3 (domain + database)
- Commit: "feat([feature]): add [Name] entity and repository"

**Batch 2: Business Logic**
- Tasks 4-5 (service + API)
- Commit: "feat([feature]): add [Name] service and endpoints"

**Batch 3: Frontend**
- Task 6 (UI)
- Commit: "feat([feature]): add [Name] UI components"

**Batch 4: Quality**
- Task 7 (tests)
- Commit: "test([feature]): add e2e tests for [Name]"

---

## Risks and Mitigations

- **[Risk from discovery.md]:** [mitigation in plan]

---

## Metadata
{"updated":"YYYY-MM-DD","sessions":N,"by":"[subagent]"}

Phase 5: Validate and Persist

Checklist before saving:

• All tasks have estimate (S/M/L)
• Dependencies between tasks are correct
• Paths are concrete and verifiable
• Batches make sense for commits
• Metadata updated

---

Batching Strategy

Task count	Strategy
<5 tasks	Single batch
5–10 tasks	2–3 batches per layer
>10 tasks	Batches per domain/module

Commit rules: one semantic commit per batch — see add-commit skill for Conventional Commits type detection and message logic.

---

Rules

Do: base tasks on about.md and discovery.md; include dependencies; estimate every task (S/M/L); use concrete paths; one semantic commit per batch.

Don't: vague tasks ("implement feature"); estimates without criteria; ignore dependencies; plan without prior docs; batches >5 tasks.