Feature Planning

feature-planning

When to use

Use this skill when:

• The user has a feature idea they want to explore or plan
• An existing feature plan needs refinement
• A feature plan needs to be turned into actionable roadmaps

Do NOT use when:

• Bug fixes (use bug-analyzer skill)
• Simple, well-understood changes that don't need planning

Procedure: Plan a feature

1. Gather requirements — What problem does this solve? Who benefits? What's the expected outcome? Run a cross-source discrepancy scan (per cross-source-consistency, gated by consistency.cross_source): where the source ticket carries text + an attachment/mockup, or leaves a clearly-needed behavior unstated (weekend/holiday shift, empty/error state, timezone), surface the conflict/gap as an Open question before drafting phases — an inferred behavior is a scope expansion to confirm, not to bake in. See cross-source-consistency-mechanics.
2. Analyze scope — Which modules, routes, models, services are affected?
3. Write the plan — Create a feature plan document (see template below).
4. Verify — Confirm all affected areas are identified, no missing dependencies.

A feature plan captures the "what and why" of a feature:

• Problem it solves, who benefits, expected outcome
• Scope, affected modules, technical approach
• Open questions and decisions

A roadmap captures the "how and when" — the step-by-step implementation plan. Feature plans and roadmaps are linked but separate concerns.

File structure

agents/features/                         # Project-wide feature plans
├── {feature-name}.md

app/Modules/{Module}/agents/features/    # Module-scoped feature plans
├── {feature-name}.md

.augment/templates/
└── features.md                          # Feature plan template

Roadmaps generated from features live in agents/roadmaps/ (or module-level agents/roadmaps/).

Feature lifecycle

Quick workflow (small features)

Explore → Plan → Refine → Roadmap → Implement
  ↑                ↑
  └── iterate ─────┘

Full workflow (complex features, 7 phases)

Use the full workflow for features that span multiple files, require architecture decisions, or have unclear requirements. Trigger with /feature:dev.

Discovery → Exploration → Questions → Architecture → Implementation → Review → Summary

Phase 1: Discovery

• Clarify the feature request — what problem does it solve?
• Identify constraints, requirements, and affected users.
• Understanding Lock (Hard Gate): Summarize understanding in 5–7 bullets covering: what is being built, why, who it's for, key constraints, explicit non-goals.
• List all assumptions explicitly.
• Wait for explicit confirmation before proceeding. Do NOT design until confirmed.

Phase 2: Codebase Exploration

• Search for similar features in the codebase.
• Map the architecture and abstractions in the affected area.
• Identify key files, services, models, routes involved.
• Present findings with file references.

Phase 3: Clarifying Questions

• Review codebase findings against the feature request.
• Identify underspecified aspects: edge cases, error handling, integrations, backward compatibility.
• Non-functional requirements — explicitly clarify or propose defaults for:
  • Performance expectations (response time, throughput)
  • Scale (users, data volume, concurrent requests)
  • Security / privacy constraints
  • Reliability / availability needs
  • Maintenance and ownership expectations
• Present all questions in an organized list.
• Wait for answers before proceeding.

Phase 4: Architecture Design

• Design 2-3 implementation approaches with different tradeoffs:
  • Minimal changes — smallest change, maximum reuse.
  • Clean architecture — maintainability, elegant abstractions.
  • Pragmatic balance — speed + quality.
• Present comparison with pros/cons and a recommendation.
• Ask the user which approach to use (present as numbered options).

Phase 5: Implementation

• Wait for explicit approval before starting.
• Follow chosen architecture from Phase 4.
• Follow codebase conventions strictly.
• Track progress via task list or roadmap.
• One behavior at a time: the failing test for that behavior, observed failing, then the minimum code that makes it pass, then the next behavior. Tests are a step of this phase, never a follow-up suggested in Phase 7 — a plan that reaches the summary owing its tests planned test-after. Exceptions are the Do-NOT list in the test-driven-development skill, and a skipped cycle is recorded in the decision log rather than passed over.

Phase 6: Quality Review

• Review the implementation for:
  • Simplicity, DRY, elegance.
  • Bugs and correctness.
  • Convention adherence.
• Present findings with severity levels.
• Ask what to fix now vs. later.

Phase 7: Summary

• Summarize what was built, key decisions, files modified.
• Suggest next steps (documentation, follow-up features) — never tests, which Phase 5 already closed per behavior.
• Update roadmap if applicable.

Decision log

Maintain a running decision log throughout the planning process. For each decision:

• What was decided
• Alternatives considered
• Why this option was chosen

Include the decision log in the feature plan file under a ## Decisions section. This ensures future developers (and agents) understand the reasoning, not just the outcome.

Bite-sized task granularity (structural roadmaps only)

When a feature plan's generated roadmap declares complexity: structural in its frontmatter, every task bullet must be self-contained and 2–5 minutes of work. Lightweight roadmaps (the default) skip this section — coarse-grained tasks are correct when the work is well-scoped and low-risk — but coarse means one behavior, not one layer: ("Reject login with an unknown email — test, then handler", "Reject login with a wrong password — test, then handler"), never an implementation step followed by an "Update tests" step.

Structural roadmap tasks must include:

1. Exact file path — app/Modules/Auth/Services/LoginService.php, never "the login service".
2. Complete code — every method body, import, and signature ready to paste; no // existing code ellipses, no ….
3. Exact command — the precise CLI invocation, never "run the migration". Examples: php artisan migrate --path=database/migrations/2026_05_09_create_logins.php (Laravel), bin/console doctrine:migrations:migrate --no-interaction (Symfony), bin/rails db:migrate VERSION=20260509… (Rails), npx prisma migrate deploy (Prisma), alembic upgrade +1 (Python / Alembic), sqlx migrate run (Rust).
4. Expected output — what success looks like (Migrated: 2026_05_09_create_logins) and the exit code.
5. No placeholders — angle-bracket placeholders, TODO, FIXME, tbd, and ??? are blockers; resolve before the task ships.

The complexity flag lives in the roadmap's YAML frontmatter:

---
complexity: structural   # triggers bite-sized granularity
# or
complexity: lightweight  # default — skips bite-sized granularity
---

Source: adapted from an external reference; complexity-gating is our addition (Council Round 1, Q4 — mitigates UX pushback for senior engineers on well-scoped work).

The four plan criteria — what a reviewer fails a plan on

The 3-scan self-review below catches mechanical gaps. These four catch the plan itself. Each is written so a reviewer can fail on it: the criterion states what failing looks like, not what passing feels like. A plan that cannot be failed on any of the four has not been reviewed, it has been read.

1. Necessity — every phase, step and artifact in the plan is traceable to a stated problem or acceptance criterion. Fails when the plan contains work no requirement asked for: a new abstraction with one caller, a migration for a field nothing reads, a "while we're in there" refactor, a config surface nobody requested. Name the orphan step and the requirement it does not map to.
2. Sufficiency — every stated requirement and acceptance criterion is discharged by at least one step. Fails when a requirement has no owning step, or when the only step that claims it is a heading with no verifiable outcome under it. This is the mirror of Necessity and is checked in the opposite direction: walk the requirements, not the steps.
3. Ordering — no step depends on the outcome of a step that comes after it, and the load-bearing unknown is resolved before the work that assumes it (see complexity-first-planning). Fails when step N consumes something step N+2 creates, or when the plan builds three cheap phases on an integration nobody has proven yet.
4. Groundedness — every command, skill, command-verb and tool the plan tells someone to run exists. Fails when the plan names a verb, skill or command that is not in the index. Check it against CAPABILITIES.yaml at the repository root — the generated capability index listing every shipped skill and command per capability area — plus the project's own script/task entry points for anything the index does not cover. This is the one of the four that is decidable without judgement, so it is the one that should never be waved through.

A failure on any of the four is a blocker, not a note: fix the plan and re-run the criterion, or move the item to Open questions with the reason.

Self-review (3-scan checklist)

Before presenting any plan, run these three scans in order. Each is a fast pass — not a deep review. Failures block presentation; fix and re-scan.

1. Spec coverage — every requirement, AC bullet, or constraint from the input has a corresponding section / AC / scope item in the plan. Walk the input top-to-bottom; tick each requirement against the plan; missing items become open questions or new AC.
2. Placeholder / TODO scan — grep the draft for <placeholder>, TODO, FIXME, tbd, ???, XXX. Either resolve them now or surface them in the Open questions section. No placeholder ships unflagged.
3. Type / shape consistency — proposed data structures, API shapes, file paths, and module names match existing codebase patterns. Cite at least one existing file per new structure as the convention anchor.

This scan is separate from adversarial-review (below). Self-review catches mechanical gaps (missing AC, leftover placeholders, mis-shaped types); adversarial-review challenges the plan's reasoning.

Source: adapted from an external reference.

Adversarial self-review

After the 3-scan self-review passes, run the adversarial-review skill before presenting. Focus on the "Feature plans / Architecture" attack questions. See that skill for the full process.

Feature plan format

See .augment/templates/features.md for the full structure. Key sections:

• Problem — What pain point does this solve?
• Proposal — What's the solution?
• Scope — What's in, what's out?
• Affected Areas — Which modules, models, services, routes?
• Technical Approach — High-level architecture decisions
• Non-Functional Requirements — Performance, scale, security, reliability
• Decisions — Decision log with alternatives and reasoning
• Open Questions — Unresolved decisions
• Roadmaps — Links to generated roadmap files

Integration with other systems

Sessions

- **Feature:** `agents/features/my-feature.md`

Roadmaps

Feature plans link to their roadmaps in the ## Roadmaps section. Roadmaps reference their source feature in the ## Context section.

Modules

If a feature is scoped to a single module, the feature plan and roadmaps live in the module's agents/ directory:

• Feature: app/Modules/{Module}/agents/features/
• Roadmaps: app/Modules/{Module}/agents/roadmaps/

Behavior rules

Research before planning

Before creating a feature plan, always:

1. Search the codebase for related code, existing patterns, and affected areas.
2. Read module docs if the feature touches a specific module.
3. Check existing features in agents/features/ for overlap or dependencies.

Be collaborative

• Ask questions — don't assume requirements.
• Challenge scope — suggest what can be deferred.
• Show tradeoffs — present options with pros/cons.
• Validate feasibility — check if the codebase supports the approach.

Keep it navigational

Feature plans are decision documents, not implementation guides. Implementation details belong in roadmaps.

Output format

1. Feature plan document following the template structure
2. Decision log with rationale for key choices
3. Implementation roadmap with ordered tasks

Auto-trigger keywords

• feature planning
• feature exploration
• feature roadmap
• requirements

Gotcha

• Don't plan features without understanding the business context — ask the user before assuming.
• The model tends to over-engineer plans — start with the simplest viable solution.
• A plan without acceptance criteria is incomplete — always define what "done" means.
• Don't create plans for features that already exist — search the codebase first.

Do NOT

• Do NOT create feature plans without user input — always collaborate.
• Do NOT skip codebase research — always check what exists.
• Do NOT put implementation steps in the feature plan — that's the roadmap's job.
• Do NOT commit or push without permission.
• Do NOT duplicate information from AGENTS.md or module docs.