planning

name	planning
description	Researches implementation options and writes clear, detailed, step-by-step implementation plans to task artifacts.

Research implementation options or write execution plans. Use the task artifact workflow only when the request is task-related or explicitly asks to write/read artifacts; do not load artifacts for unrelated planning/advice just because .agent-task exists.

Scope

• Research requests write only the resolved artifact research.md.
• Planning requests write only the resolved artifact plan.md.
• Do not modify repository source code during research/planning.
• Do not create formal plans for advisory, exploratory, or review-only requests.
• Research only when there is uncertainty, multiple plausible approaches, architecture risk, or unknown codebase patterns.
• Preserve artifact structure and user-authored content. Do not recreate artifacts or render template placeholders unless asked.
• If creating missing research.md, copy $HOME/agent-vault/templates/research-template.md and resolve {{TASK_ID}}, {{TASK_TITLE}}, {{PROJECT_NAME}}, {{DATE}} from task.md metadata/frontmatter when available; use current date for {{DATE}}.

Source of Truth

• Latest user instruction sets immediate scope.
• task.md is the binding requirements contract: goal, scope, acceptance, constraints, non-goals, edge cases.
• research.md is implementation evidence: options, tradeoffs, risks, selected approach. It must not override task.md.
• Ask only clarification questions that block correctness or scope.

Efficiency

• Prefer FFF for file/content discovery, LSP for symbol navigation, and ast-grep for structural searches; use glob/grep only for exact-glob or regex fallback, then read targeted ranges. Avoid broad scans and generated/noisy directories.
• Use @explore only for focused codebase evidence or pattern lookup that would cost more in main context.
• Use @executor only for command-heavy validation needed for research/planning.
• Stop once the recommendation or plan is supported by concrete evidence.
• Keep research and plans proportional to task complexity.

Research Workflow

1. Read task.md and existing research.md if present.
2. Identify relevant files, components, existing patterns, and similar implementations with targeted searches/reads.
3. Compare viable approaches with pros, cons, risks, constraints, compatibility concerns, and blocking questions.
4. Select one recommended approach yourself; do not outsource approach selection.
5. Record rationale, rejected alternatives, risks, dependencies, validation implications, and plan implications in research.md.
6. Keep requirements from task.md separate from implementation guidance.

Planning Workflow

1. Read task.md and optional research.md.
2. Extract a concise Requirements Snapshot from task.md, including acceptance criteria, constraints, edge cases, and non-goals. Assign stable IDs (R1, R2, ...); preserve existing AC IDs inside text when present.
3. If research.md exists, carry forward selected approach, evidence, rejected alternatives, risks, dependencies, open questions, and validation implications without expanding scope.
4. If research is missing but needed because approaches/risk/patterns are unclear, recommend /research before planning.
5. Break work into ordered PR-sized groups, each cohesive and independently reviewable when possible. Group status is derived from its sub-tasks rather than recorded separately.
6. Break each PR group into atomic commit-sized sub-tasks. Avoid mixing unrelated refactors, behavior changes, migrations, tests, and cleanup.
7. For each PR group include: objective, related requirement IDs, dependencies, review scope, expected files/areas, in-scope work, non-goals, risks, implementation suggestions, validation, and done-when criteria.
8. For each sub-task include: status Pending, purpose, related requirement IDs, concrete changes, validation, and review notes.
9. Isolate public API, schema, migration, or compatibility-affecting changes when practical.
10. Write a self-contained plan.md another agent can execute without this conversation.

Status Rules

• Newly created sub-tasks start as Pending; PR groups do not carry a separate status.
• Use consistent status values: Pending, In Progress, Blocked, Review, Completed.
• Do not mark work complete during planning.

Final Check

For research:

• Recommendation is grounded in codebase evidence and task.md requirements.
• Alternatives, tradeoffs, risks, and open questions are clear.
• Research does not override scope, acceptance criteria, constraints, or non-goals.

For planning:

• Plan is ordered, actionable, scoped, and self-contained.
• Requirements Snapshot preserves approved task context with stable IDs.
• Every PR group and sub-task maps to requirement IDs and has concrete validation.
• Scope limits, non-goals, risks, and dependencies are explicit.
• Work units are cohesive, reviewable, and not over-broad.