sp-planning

Planning

Overview

Plan by understanding reality first, then designing, then writing. Bad plans come from designers who don't read the codebase first.

Assume the worker is a skilled developer, but knows almost nothing about our toolset or problem domain. Document everything they need: which files to touch, a clear description of what to do (before/after code for non-obvious changes), build/test commands, commit messages. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Announce at start: "I'm using the planning skill to create the implementation plan."

First action: Run ttal project list to identify the target project before writing anything.

Designer Rules

1. Never write code — you write plans, not implementations
2. Never execute without approval — plans wait for explicit go-ahead
3. Always plan first — no exceptions, even for "quick fixes"
4. Design at structure level — before adding behavior, question whether the existing structure supports it cleanly. Refactor first if needed.

Project Scope Gate

Rule: 1 task → 1 plan → 1 project/repo.

Before writing any plan, you MUST confirm the target project:

1. Run ttal project list — see all available projects
2. Check the task's project field — if it has one, use it as a hint for the target alias, then confirm with ttal project get <alias>
3. If no project field — ask explicitly: "Which repo does this plan target?"
4. Validate the repo exists — run ttal project get <alias> to confirm the path

Hard rule: Do NOT proceed past this gate without a confirmed single target repo.

When Scope Is Too Big

If a task touches multiple projects/repos, the scope is too big for a single plan. Split it:

1. Identify the repos involved — list every repo the task would touch
2. Extract separate tasks — one task per repo, each with its own clear goal
3. Set task dependencies — use task <uuid> modify depends:<other-uuid> so phases execute in order (ttal doesn't expose depends — use taskwarrior directly for this)
4. Write separate plans — one plan per task, each scoped to its single repo
5. Link plans via Depends on — reference the other plan/task in the header

Example: "Add auth to API and update frontend to use it" → split into:

• Task A: ttal task add --project api "Add auth endpoint" → Plan A (api repo)
• Task B: ttal task add --project frontend "Integrate auth endpoint" → Plan B (frontend repo), depends on Task A

Scope Violations — What to Flag

• Plan references files in multiple repos → stop and split into separate tasks + plans
• Task touches multiple projects → scope is too big, extract per-repo tasks with dependencies
• Plan says "update the API and the frontend" without specifying they're the same repo → clarify, likely needs splitting
• Task has no project field and plan doesn't state one → ask before writing
• Plan's target repo doesn't match the task's project field → reconcile before proceeding

Phase 1: Explore Reality

BEFORE writing ANY plan, understand what exists. Don't design in the abstract — read the code.

1. Read existing code — find and read the files/modules the task would touch. Understand current patterns, naming conventions, architecture.
2. Identify constraints — what does the existing code assume? What interfaces, types, configs are already in place?
3. Check prior art — has this been attempted before? Search flicknote (flicknote find <keywords>) and completed tasks (ttal task find <keywords> --completed) for related work.
4. Map dependencies — what must exist before this works? What other modules, services, configs does this touch?

Output: A mental model of the current state. If something surprises you, note it — surprises in Phase 1 prevent disasters in implementation.

Red Flags — STOP and Investigate

• You're planning changes to code you haven't read → read it first
• The task assumes a structure that doesn't exist → flag it
• You find recent changes that conflict with the task's assumptions → reconcile before planning

Checkpoint 1: Discuss Approach

After Phase 1, talk through what you found before designing. Don't go silent and start writing — discuss first.

Conversational checkpoint:

• State what you found in the codebase: current patterns, constraints, surprises from Phase 1 (conversational summary, not written output)
• Propose your approach: 'I'm thinking we should do X because Y. The trade-off is Z.'
• Ask for alignment: 'Does this approach make sense, or should I consider something different?'
• Keep it lightweight: 3-5 sentences of understanding + proposed approach + a question
• If not aligned → revise approach and discuss again. Do not proceed to Phase 2 without explicit agreement.

⛔ STOP here. End your message after presenting your findings and question. Do not begin Phase 2 or write the orientation doc until the human responds and confirms alignment.

Then, for complex tasks, capture the orientation:

cat <<'ORIENT' | flicknote add --project orientation
# Orientation: [Feature Name]
## What
One sentence: what are we building/changing?
## Why
What problem does this solve? What's the motivation?
## Approach
Which approach are we taking and why? (If you evaluated alternatives in Phase 1, note the decision here.)
## Anti-goals
What is this NOT doing? (Prevents scope creep during implementation.)
ORIENT

Annotate the task: task <uuid> annotate "orientation: <flicknote-hex-id>"

When to skip the orientation doc: Simple bug fixes, mechanical refactors, tasks where what/why is obvious from the description. If the task description already answers what/why/approach, skip the doc. The conversational checkpoint still happens.

When to write the orientation doc: Multi-file features, architecture decisions, anything where a worker might ask 'but why are we doing it this way?'

---

(Note: the orientation doc writing happens AFTER the conversation confirms the approach — not before.)

Phase 2: Design

With reality understood, now design the solution:

1. Define exit criteria — what does "done" look like? How does the worker know they've succeeded? Be specific: "all tests pass" is not enough — which tests, what behavior.
2. Define anti-goals — what is this plan NOT doing? Prevents scope creep during implementation.
3. Evaluate scope — can this be split into smaller PRs? Plans touching 40+ files are red flags. Prefer incremental delivery.
4. Choose the approach — given what you found in Phase 1, what's the simplest path? Consider alternatives briefly, pick one, justify it.
5. Identify test strategy — unit, integration, manual? Workers shouldn't have to decide this.

Design Discipline

• Look for abstractions before patching: When fixing a bug, ask "what are the right primitives?" not just "how do I fix this case?"
• Treat justified duplication as a smell: If you catch yourself saying "this duplication is fine because X is rare," that's a signal to refactor, not rationalize
• Design at structure level, not code level: Before adding new behavior, question whether the existing structure supports it cleanly. Refactor first if needed.

Phase 3: Write the Plan

Now write. The default format is a task tree — subtasks under the parent task. Each subtask = one step the worker executes and marks done. Use flicknote for orientation docs (what/why context) alongside the tree when needed.

Plan Quality Checklist

Every subtask in the plan MUST have:

• Files — exact paths to create, modify, and test
• What to do — clear description, not just "add validation." For complex changes, include before/after code.
• Build/test commands — exact commands with expected output (can be in parent task or final subtask)
• Commit message — ready to copy-paste
• Self-contained — worker can execute without asking questions

If a subtask fails this checklist, it's not ready.

Orientation Header (flicknote)

When writing a flicknote orientation doc alongside the task tree, start with:

# Plan: [Feature Name]

**Project:** [ttal project alias — e.g. `ttal-cli`]
**Goal:** [One sentence describing what this builds]
**Anti-goals:** [What this plan is NOT doing — or "None"]
**Depends on:** [Other plans/tasks, or "None"]

---

Task Structure (task tree format)

Each ## heading becomes a subtask. Body text becomes the subtask's annotation. Workers see these via task <uuid> tree and mark each done on completion.

## Add validation layer
Add input validation to the API handler. Check required fields, validate types, return 400 on failure.

Files: `internal/api/handler.go` (modify), `internal/api/handler_test.go` (create)

Step 1: Write failing test for missing required fields
Step 2: Implement validation, run tests
Step 3: Commit — `feat(api): add input validation to handler`

## Write integration tests
Integration tests for the full validation flow.

Files: `internal/api/integration_test.go` (create)

Step 1: Write integration test hitting the handler endpoint
Step 2: Run `make test`, verify pass
Step 3: Commit — `test(api): add validation integration tests`

Each subtask is self-contained: files, steps, commit message. The worker executes them in order and marks each done with task <subtask-uuid> done.

Subtasks execute in tree order — arrange them accordingly. For hard ordering constraints, use task <uuid> modify depends:<other-uuid>.

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

Phase 4: Validate

Before declaring the plan done, check it against reality:

1. Does the plan account for what you found in Phase 1? — constraints, existing patterns, dependencies
2. Are the file paths real? — verify every path in the plan exists (or is clearly marked as "Create")
3. Is the scope reasonable? — if it's more than ~5 tasks, consider splitting into phases
4. Would a worker need to ask questions? — if yes, the plan isn't ready

Plan Storage

Inline Plans (small tasks)

For tasks with <=6 steps or single-file mechanical changes, annotate the task directly:

ttal task add --project <alias> "description" --tag planned
task <uuid> annotate 'Plan: 1. Do X 2. Do Y 3. Do Z'

Task Tree Plans (default for structured plans)

For multi-step plans, create a subtask tree. The tree IS the plan — each subtask is a step, annotations hold details.

cat <<'PLAN' | task <parent-uuid> plan
## Step 1: Title
Details and context for this step.

## Step 2: Title
Details and context for this step.
PLAN

# View the plan
task <parent-uuid> tree

# Iterate
cat updated.md | task <parent-uuid> plan replace

No separate annotation needed — the subtasks are already under the parent task.

Flicknote (orientation docs)

For orientation docs (what/why context): flicknote add --project orientation

task <uuid> annotate 'orientation: flicknote <hex-id>'

Decision rule: If the plan fits in annotations → inline. If it's an ordered set of execution steps → task tree. If you need to capture what/why/trade-offs separately → flicknote orientation alongside a task tree.

After the Plan Is Written

Save the plan first:

• Inline: annotate the task directly
• Task tree: cat plan.md | task <parent-uuid> plan
• Orientation: flicknote add --project orientation, then task <uuid> annotate '<hex-id>'

Then chain into the completion phase — it handles self-review, open questions, summary, and review handoff with proper output-channel partitioning:

skill get sp-complete-design

Follow every step in that skill. Do not duplicate its logic here.

Remember

• Explore reality before designing — read the code first
• Exact file paths always
• Clear description of what to do; before/after code for non-obvious changes
• Exact commands with expected output
• DRY, YAGNI, TDD, frequent commits
• Worker should never need to ask questions