Design -- Deep Discovery & Specification Skill

Design -- Deep Discovery & Specification

Full-ceremony specification process for ambitious features. Produces the same spec.md + plan.md output as /maestro:new-track but through deep, multi-step discovery inspired by BMAD methodology.

When to use this instead of /maestro:new-track:

Multi-component systems with many moving parts
Regulated domains (healthcare, fintech, govtech)
Unclear or complex requirements that need thorough discovery
Features where getting the spec wrong is expensive

Arguments

$ARGUMENTS

The track description. Examples: "Add user authentication with OAuth and RBAC", "Build real-time collaboration engine", "Implement HIPAA-compliant patient portal"

Step Sequence

This skill uses a step-file architecture. Each step is a self-contained file in reference/steps/. You MUST load ONE step at a time, execute it fully, then load the NEXT. Previous step files get dropped from context.

Rules:

NEVER load multiple step files simultaneously
ALWAYS read the entire step file before executing
NEVER skip steps or reorder the sequence
Steps 4-9 include an A/P/C menu -- the user MUST select [C] before you proceed

Step 1: Validate Prerequisites

Check product.md and tracks.md exist. --> Read and follow reference/steps/step-01-init.md

Step 2: Parse Input & Generate Track ID

Extract description, infer type, generate {shortname}_{YYYYMMDD} ID. --> Read and follow reference/steps/step-02-parse-input.md

Step 3: Create Track Directory

Create .maestro/tracks/{track_id}/. --> Read and follow reference/steps/step-03-create-dir.md

Step 4: Project Classification

Classify project type, domain, and complexity using reference/classification-data.md. --> Read and follow reference/steps/step-04-classification.md

Step 5: Vision & Success Criteria

Define vision, measurable success criteria, and MVP/Growth/Vision scope. --> Read and follow reference/steps/step-05-vision.md

Step 6: User Journey Mapping

Map ALL user types with narrative journeys. Minimum 3 journeys. Extract capability hints. --> Read and follow reference/steps/step-06-journeys.md

Step 7: Domain & Scoping

Domain-specific requirements and risk analysis. Skipped if domain=general AND complexity=low. --> Read and follow reference/steps/step-07-domain.md

Step 8: Functional Requirements Synthesis

Synthesize FRs from all discovery. Grouped by capability area. Each FR testable and implementation-agnostic. --> Read and follow reference/steps/step-08-functional.md

Step 9: Non-Functional Requirements

Performance, security, scalability, compatibility. Measurable format. --> Read and follow reference/steps/step-09-nonfunctional.md

Step 10: Spec Draft & Approval

Compose enriched spec from all discovery. Present for approval. Write spec.md. --> Read and follow reference/steps/step-10-spec-approval.md

Step 11: Codebase Pattern Scan

Scan codebase for existing patterns relevant to this track. Feed into plan context. --> Read and follow reference/steps/step-11-codebase-scan.md

Step 12: Implementation Plan with Traceability

Generate plan with FR traceability and coverage matrix. Present for approval. Write plan.md. --> Read and follow reference/steps/step-12-plan.md

Step 13: Detect Relevant Skills

Scan runtime skill list for skills matching this track's domain/tech. Store matches in metadata.json. --> Read and follow reference/steps/step-13-skills.md

Step 14: Plan-to-BR Sync

If Beads (BR) is available and initialized, sync plan into BR epics/issues. Skip if not available. --> Read and follow reference/steps/step-14-br-sync.md

Step 15: Pre-Implementation Readiness Gate

Validate FR coverage, AC coverage, dependency sanity, scope alignment. Pass/fail gate. --> Read and follow reference/steps/step-15-readiness.md

Step 16: Metadata, Registry, Commit & Summary

Write metadata.json, update tracks.md, commit, display summary. --> Read and follow reference/steps/step-16-commit.md

When Design Is "Done Enough"

Design is not a goal -- it is a gate. You are done when an autonomous agent can execute the plan without asking questions.

The Handoff Test: Read every task in the plan. For each one, ask: "Could a worker agent execute this with zero clarification?" If the answer is no for any task, the design is not done.

Done criteria:

[ ] Every task has exact file paths, complete code snippets, and executable verification commands
[ ] No task says "add validation" or "implement error handling" -- it says what, where, and how
[ ] Dependencies form a DAG (no cycles, infrastructure before consumers)
[ ] Coverage matrix shows 0 orphaned FRs
[ ] Readiness gate passes (step 15)
[ ] Each design decision has a stated reason (not just a choice)

Not done criteria (keep going):

A task requires domain knowledge that is not in the spec or context files
Verification steps say "manually check" or "visually confirm"
Two tasks modify the same file with no dependency between them
A task's "What to do" section requires inference about the codebase

Design-to-Plan Bridge

Design produces spec.md. Plan-write consumes it. The bridge between them is how design decisions become task structure.

How Design Decisions Map to Tasks

| Design artifact | Becomes in plan | |-----------------|-----------------| | FR (functional requirement) | One or more tasks with Addresses: FR-N | | User journey | Sequence of tasks ordered by journey flow | | Domain constraint | Task guardrail in Must NOT do section | | NFR (performance, security) | Verification command in task's Verify section | | Codebase pattern (step 11) | Code snippets that follow the existing convention | | Out-of-scope item | Explicit exclusion in task's Must NOT do |

The plan-write Connection

After design completes, the approved spec feeds directly into maestro plan-write --feature <name>. The plan-write command expects:

A ## Discovery section (min 100 chars) -- summarize what design discovered
FR references -- plan tasks trace back to spec FRs via Addresses: FR-N
Non-Goals / Ghost Diffs -- derived from the spec's Out of Scope section
Context files -- design should save key findings via maestro context-write so plan-write can reference them

Output contract: Design produces spec.md + plan.md. The maestro:implement skill consumes both. The spec is the "what", the plan is the "how and in what order."

Task Structure & Handoff

When the plan reaches the task-writing stage, apply these conventions to every task.

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

Task Dependencies

The Depends on annotation declares task execution order:

Depends on: none -- No dependencies; can run immediately or in parallel
Depends on: 1 -- Depends on task 1
Depends on: 1, 3 -- Depends on tasks 1 and 3

Always include Depends on for each task. Use none to enable parallel starts.

Maximize parallelism. If two tasks touch different files and have no data dependency, they should both be Depends on: none or depend only on shared infrastructure tasks.

Task Template

### N. Task Name

**Depends on**: none
**Addresses**: FR-1, FR-3

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

**What to do**:
- Step 1: Write the failing test
  ```python
  def test_specific_behavior():
      result = function(input)
      assert result == expected
  ```
- Step 2: Run test to verify it fails
  - Run: `pytest tests/path/test.py::test_name -v`
  - Expected: FAIL with "function not defined"
- Step 3: Write minimal implementation
  ```python
  def function(input):
      return expected
  ```
- Step 4: Run test to verify it passes
  - Run: `pytest tests/path/test.py::test_name -v`
  - Expected: PASS
- Step 5: Commit
  ```bash
  git add tests/path/test.py src/path/file.py
  git commit -m "feat: add specific feature"
  ```

**Must NOT do**:
- {Task guardrail -- derived from domain constraints and out-of-scope items}

**References**:
- `{file:lines}` -- {Why this reference matters}

**Verify**:
- [ ] Run: `{command}` --> {expected}
- [ ] {Additional acceptance criteria}

All verification MUST be agent-executable (no human intervention):
  `bun test` --> all pass
  `curl -X POST /api/x` --> 201
NOT: "User manually tests..."
NOT: "Visually confirm..."

Remember

Exact file paths always
Complete code in plan (not "add validation")
Exact commands with expected output
Reference relevant skills with @ syntax
DRY, YAGNI, TDD, frequent commits
All acceptance criteria must be agent-executable (zero human intervention)
Every task must have Addresses: FR-N tracing back to the spec

Design Review Checklist

Before approving the spec (step 10) or plan (step 12), run this checklist mentally.

Spec Review

| Check | Pass | Fail | |-------|------|------| | Every FR is testable | "System returns 401 for unauthorized requests" | "System handles auth" | | Success criteria are measurable | "Response time < 200ms p95" | "System is fast" | | MVP scope is ruthlessly small | 3-8 FRs for MVP | 15+ FRs all marked MVP | | Out of scope is explicit | "No admin dashboard in MVP" | Silence on boundaries | | Edge cases derived from journeys | Error paths from step 6 journey mapping | "Handle errors appropriately" | | Domain constraints are specific | "PHI must be encrypted at rest (AES-256)" | "Follow HIPAA" |

Plan Review

| Check | Pass | Fail | |-------|------|------| | Coverage matrix has 0 orphans | Every FR mapped to a task | FR-7 shows -- | | Tasks are self-contained | Worker can execute without asking questions | "Implement the auth layer" | | Dependencies are minimal | Max 2-3 deps per task | Task 8 depends on 1,2,3,4,5 | | Verification is executable | bun test -- auth --> all pass | "Check it works" | | No implicit ordering | Explicit Depends on for every task | "Do this after the DB task" | | Phase boundaries are meaningful | Each phase produces a testable increment | Phases split arbitrarily |

Over-Engineering Traps

Design invites over-engineering. Recognize these patterns and cut them.

| Trap | Signal | Fix | |------|--------|-----| | Abstraction astronautics | "Let's build a plugin system so we can..." | Build the concrete thing. Abstract when the second use case appears. | | Premature generalization | "This should work for any provider, not just Stripe" | Build for Stripe. Add the interface when provider #2 arrives. | | Spec-driven scope creep | "While we're at it, we should also..." | Check the MVP tier. If it's not MVP, it goes in Growth. | | Architecture tourism | "We should use event sourcing / CQRS / microservices" | Does the simplest architecture fail? If not, use the simplest architecture. | | Defensive over-specification | 25+ FRs for a CRUD feature | If classification says "low complexity", the spec should be short. Match depth to complexity. | | Gold-plated NFRs | "99.99% uptime" for an internal tool | Match NFRs to actual user expectations. Internal tools do not need carrier-grade SLAs. |

The test: For every design decision, ask: "What is the simplest thing that could work?" If your design is more complex than that, you need a stated reason why.

Execution Handoff

After saving the plan, the design phase is complete. The handoff artifact is:

.maestro/tracks/{track_id}/
  spec.md    -- What to build (from step 10)
  plan.md    -- How to build it, in what order (from step 12)

These two files are the complete handoff. The maestro:implement skill consumes them.

Transition options:

maestro plan-write (recommended for hive workflows) -- Run maestro plan-write --feature <name> with the plan content. This enters the standard hive workflow: plan-approve, tasks-sync, worktree-start.
maestro:implement (direct execution) -- Open new session with maestro:implement. The skill reads spec.md and plan.md, then executes tasks sequentially with checkpoints.
Subagent-driven (this session) -- Stay in this session. Dispatch a fresh subagent per task. Review between tasks. Fast iteration but no worktree isolation.

Before handing off, verify:

Readiness gate passed (step 15)
All context files saved via maestro context-write
Track metadata committed (step 16)

Relationship to Other Commands

maestro init -- Initialize maestro for the project (run first)
maestro feature-create -- Create a feature to work on
/maestro:design -- You are here. Deep discovery for ambitious features
maestro plan-write -- Write the plan from design output (feeds into task-sync)
maestro plan-approve -- Approve the plan for execution
maestro task-sync -- Generate tasks from approved plan
/maestro:implement -- Execute the implementation plan
/maestro:review -- Verify implementation against spec
maestro status -- Check progress across all features

A track created here produces spec.md and plan.md that maestro:implement or maestro plan-write consumes. The enriched spec serves as the baseline for maestro:review. Deep specs lead to better implementations -- invest in the discovery.

Agent Skills: Design -- Deep Discovery & Specification

Install this agent skill to your local

Skill Files