Elaborate

Elaborate Plans

Elaborate existing Plans with detailed, actionable guidance distilled from higher-quality models, filling gaps and making them easier for simpler models to execute during development.

Pre-flight

• {{WORKSPACE}} = workspace root. Resolve once per session and reuse: git rev-parse --show-toplevel; fall back to cwd outside a git repo.
• Before your first write, read {{WORKSPACE}}/{{MAESTRO_CONFIG}}/references/conventions.md — statuses, retries, artifact paths, and file ownership are defined there and are binding.
• Working folder: {{WORKSPACE}}
• Target folders: {{WORKSPACE}}/plans/ (you should only modify files in this folder)
• Required input: Plan ID (e.g., "AUTH-001") or Plan file path (e.g., "plans/AUTH-001-user-authentication.md")

References

Read reference specs on-demand when the workflow requires them — do NOT read all upfront.

Always needed

• Plan: Read {{WORKSPACE}}/{{MAESTRO_CONFIG}}/references/plan.md — for Plan format, milestone fields (including the mandatory Retries header field), and elaboration format
• Plans Index: Read {{WORKSPACE}}/{{MAESTRO_CONFIG}}/references/plans-index.md — for index lookup and status updates

On-demand (read only when needed)

• Contexts (working file): Read {{WORKSPACE}}/knowledge/contexts.md when checking domain language for elaborations — the spec at {{MAESTRO_CONFIG}}/references/contexts.md defines the format only
• Repo Fingerprint (working file): Read {{WORKSPACE}}/knowledge/repo-fingerprint.md when checking the tech stack
• Stack Overrides (working file): Read {{WORKSPACE}}/knowledge/tech-preferences.md if present — declared categories steer which technologies guidance targets
• Instruments (working file): Read {{WORKSPACE}}/knowledge/instruments.md — if it exists, target the composition section's model as the quality bar and keep guidance executable by the implementation section's model (that is the whole point of elaboration)
• Testing Principles: Read {{WORKSPACE}}/{{MAESTRO_CONFIG}}/references/testing-principles.md — when elaborating test strategy
• Design Principles: Read {{WORKSPACE}}/{{MAESTRO_CONFIG}}/references/design-principles.md — when elaborating code patterns
• Tech Preferences: Read {{WORKSPACE}}/{{MAESTRO_CONFIG}}/references/tech-preferences.md — when elaborating tech choices

Cross-references

For how references relate to each other, see {{WORKSPACE}}/{{MAESTRO_CONFIG}}/references/references-map.md.

Validation

• If required input is missing, abort with error
• If Plan file doesn't exist in plans directory, abort with error
• If Plan is already marked as Done or Failed, abort with error

Core Workflow

Phase 0: Setup

1. Parse Input: Determine if input is a Plan ID or file path
2. Locate Plan: If Plan ID provided, read {{WORKSPACE}}/plans/index.md to find the full Plan filename
3. Read Plan: Read the full Plan file to understand its structure, milestones, and current detail level
4. Read Context: Read the working knowledge files ({{WORKSPACE}}/knowledge/contexts.md, {{WORKSPACE}}/knowledge/repo-fingerprint.md) to understand domain language and technical stack

Phase 1: Gap Analysis

1. Identify Gaps: Analyze each milestone for missing detail:
   • Vague or ambiguous implementation steps
   • Missing error handling guidance
   • Unclear testing strategies
   • Absence of code patterns or examples
   • Undefined edge cases
2. Complexity Assessment: Evaluate which milestones would benefit most from elaboration based on technical complexity and dependencies
3. Knowledge Gaps: Identify areas where external documentation or best practices would be helpful

Phase 2: Knowledge Gathering

1. Tech Stack Research: Search the web to gather:
   • Latest documentation for referenced technologies and frameworks
   • Best practices for the specific implementation patterns
   • Common pitfalls and how to avoid them
2. Codebase Patterns: Search the codebase to find:
   • Existing similar implementations in the codebase
   • Established patterns for the technology stack
   • Relevant utility functions or helper classes
3. Domain Alignment: Ensure elaboration uses terminology from the working knowledge/contexts.md

Phase 3: Elaboration Generation

For every milestone — even ones needing no other elaboration — ensure a Why & Limits block exists (add it when missing; refine it when thin). This is mandatory: it is your constraint-transmission channel to cheaper executors, and constraints embedded in the milestone get read where rules in reference docs may not. Content:

• Why: one line — the design rationale a play agent cannot infer from the task text alone (what breaks elsewhere if done differently; which milestones consume this milestone's shape)
• Must not: explicit negative scope — files/areas owned by other milestones or read-only zones (knowledge/), forbidden actions (committing, adding dependencies), each with a one-clause reason
• If blocked: return Failed with the blocker named — do not improvise outside scope

Hard limit: 3 bullets, one line each (Plan spec, Why & Limits).

For each milestone identified as needing elaboration, additionally add:

Implementation Guidance:

• Detailed step-by-step breakdown
• Specific file paths and directory structures
• Code patterns and examples following existing codebase conventions
• Prerequisite checks and setup steps
• Integration points with existing code

Error Handling:

• Common error scenarios and how to handle them
• Validation requirements
• Failure modes and recovery strategies
• Rollback procedures if needed

Testing Strategy:

• Specific test cases to implement
• Edge cases to cover
• Mock data requirements
• Test file locations and naming conventions (unit tests co-located; E2E flat in tests/)

Best Practices:

• Performance considerations
• Security considerations
• Code organization patterns
• Documentation requirements

Code Examples:

• Relevant code snippets following project conventions
• Interface implementations
• Configuration examples
• Data structure definitions

Common Pitfalls:

• Mistakes to avoid
• Anti-patterns to watch for
• Debugging hints for common issues

Phase 4: User Review

1. Present Elaborations: Present proposed elaborations to the user:
   • "I've elaborated the Plan with detailed implementation guidance, code patterns, testing strategies, and best practices. Key additions include: [summary of major elaborations]. Should I apply these enhancements to the Plan?"
   • Options: "Yes, apply all", "Review specific sections", "No, cancel"
2. Selective Review: If user chooses "Review specific sections", present elaborations section by section for approval

Phase 5: Plan Enhancement

1. Apply Elaborations: Update the Plan file with approved elaborations
2. Maintain Structure: Ensure elaborations are added without breaking the existing Plan structure and DAG dependencies
3. Preserve Metadata: Keep original Plan metadata (Test Tier, Docs Affected, Status, and every milestone's Retries count) unchanged
4. Update Index: If elaborations significantly change the Plan scope, consider updating the description in {{WORKSPACE}}/plans/index.md

Elaboration Format

Add elaborations as nested bullet points under each milestone, preserving the canonical milestone header exactly as defined in the Plan spec (including Retries):

- ⏳ **Milestone 1 (ID: 1, Dependencies: [], Retries: 0)**: [Short Title] - Specific detailed task description.
  **Why & Limits:**
  - Why: [Rationale the executor cannot infer — what breaks if done differently]
  - Must not: [Files owned by other milestones, forbidden actions — each with a one-clause reason]
  - If blocked: Return Failed with the blocker named — do not improvise outside scope.
  **Implementation Guidance:**
  - Step 1: [Detailed step with file paths]
  - Step 2: [Detailed step with specific actions]
  - Follow the pattern in [existing-file](path/to/existing-file)
  **Code Pattern:**
    ```typescript
    // Example following project conventions
    interface Example {
      // Specific implementation
    }
    ```
  **Testing Strategy:**
  - Create test file at `tests/auth.spec.ts`
  - Test cases: [specific cases]
  - Mock data: [specific mock requirements]
  **Error Handling:**
  - Handle [specific error scenario]
  - Validate [specific conditions]
  - Fallback: [specific fallback strategy]
  **Common Pitfalls:**
  - Avoid [specific mistake]
  - Watch for [specific anti-pattern]
  **Best Practices:**
  - Use [specific pattern] for [specific purpose]
  - Consider [specific performance/security implication]

Quality Checklist

Before completing the elaboration:

• Plan file successfully read and understood
• Gaps identified in existing milestones
• Knowledge gathered from documentation and codebase
• Why & Limits present on every milestone (mandatory — even milestones that needed no other elaboration)
• Elaborations follow project conventions and patterns
• Code examples match existing codebase style
• Domain language from the working contexts.md used correctly
• Testing strategies are specific and actionable
• Error handling covers common scenarios
• Best practices are relevant to the tech stack
• User approval obtained for elaborations
• Plan structure and DAG dependencies preserved
• Original Plan metadata maintained, including per-milestone Retries

Error Handling

• If Plan file cannot be found, abort with error message suggesting user check the Plans Index
• If Plan is already Done or Failed, abort with error message suggesting the Plan may not need elaboration
• If web research fails for a specific technology, note this in elaborations and proceed with codebase patterns only
• If user rejects elaborations, do not modify the Plan file
• If elaborations would fundamentally change the Plan scope, suggest creating a new Plan instead

Integration with Other Skills

• compose: Typically runs compose → elaborate → orchestrate in sequence
• orchestrate: Elaborated Plans provide better guidance for subagent execution
• rehearse: Can be called if rehearse identifies areas needing more technical detail
• tune: May recommend elaboration when an Issue reveals the Plan lacked detail

Execution

Use the Plan ID or file path from the invocation, then proceed with Phase 0: Setup.