Phase Refine Outline

Phase Refine Outline Skill

EXECUTION MODE: You are now executing this skill. DO NOT explain or summarize these instructions to the user. IMMEDIATELY begin executing the workflow steps below, starting with Step 1.

Role: Architecture-driven workflow skill for creating solution outlines. Uses pre-computed architecture data to make intelligent module and package placement decisions.

Key Insight: Module and package matching is semantic analysis that requires LLM reasoning. Scripts provide DATA, the LLM provides REASONING.

Input Parameters

Workflow Overview

┌──────────────────────────────────────────────────────────────────┐
│                ARCHITECTURE-DRIVEN WORKFLOW                      │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Step 1: Load architecture context                               │
│          → architecture info                                     │
│                                                                  │
│  Step 2: Load and understand requirements                        │
│          → manage-plan-documents read --type request             │
│                                                                  │
│  Step 3: Assess complexity (simple vs complex)                   │
│          → Decompose if multi-module                             │
│                                                                  │
│  Step 4: Select target modules                                   │
│          → Score by responsibility, purpose, packages            │
│                                                                  │
│  Step 5: Determine package placement                             │
│          → architecture module --name X --full                   │
│                                                                  │
│  Step 6: Create deliverables with Skills by Profile              │
│          → One deliverable per module                            │
│          → Skills by Profile from module.skills_by_profile       │
│                                                                  │
│  Step 7: Create IT deliverable (optional)                        │
│          → architecture modules --command integration-tests      │
│          → Separate deliverable targeting IT module              │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Step 1: Load Architecture Context

Query project architecture BEFORE any codebase exploration. Architecture data is pre-computed and compact (~500 tokens).

EXECUTE:

python3 .plan/execute-script.py plan-marshall:analyze-project-architecture:architecture info

Output format: plan-marshall:analyze-project-architecture/standards/client-api.md

If status=error or architecture not found: Return error and abort:

status: error
message: Run /marshall-steward first

Step 2: Load and Understand Requirements

Load the request document and extract actionable requirements.

EXECUTE:

python3 .plan/execute-script.py pm-workflow:manage-plan-documents:manage-plan-documents read \
  --plan-id {plan_id} --type request

Output format: pm-workflow:manage-plan-documents/documents/request.toon

Parse for:

• Functional requirements (what to build)
• Constraints (technology, patterns, compatibility)
• Explicit test requirements (unit, integration, E2E)
• Acceptance criteria

EXECUTE:

python3 .plan/execute-script.py pm-workflow:manage-config:manage-config read \
  --plan-id {plan_id}

Output format: pm-workflow:manage-config

Extract domains array - each deliverable will be assigned a single domain from this array.

Step 3: Assess Complexity (Simple vs Complex)

Determine if task is single-module (simple) or multi-module (complex):

Simple Workflow (single module)

┌───────────────────────────────┐
│       SIMPLE WORKFLOW         │
├───────────────────────────────┤
│ 1. Select target module       │
│ 2. Select target package      │
│ 3. Create deliverables        │
└───────────────────────────────┘

Complex Workflow (multi-module)

┌───────────────────────────────┐
│       COMPLEX WORKFLOW        │
├───────────────────────────────┤
│ 1. Load dependency graph      │
│ 2. Decompose into sub-tasks   │
│ 3. Run simple workflow each   │
│ 4. Aggregate deliverables     │
│ 5. Order by layers (graph)    │
└───────────────────────────────┘

For complex tasks, load the complete dependency graph to determine execution ordering.

EXECUTE:

python3 .plan/execute-script.py plan-marshall:analyze-project-architecture:architecture graph

Output format: plan-marshall:analyze-project-architecture/standards/module-graph-format.md (force load)

Detail: See standards/module-selection.md for decomposition patterns and dependency ordering.

Step 4: Select Target Modules

For simple tasks: identify the single affected module. For complex tasks: select module for each sub-task.

Module Selection Analysis

For each candidate module, evaluate:

Selection threshold: Modules with weighted score >= 6 are candidates.

Query Module Details

For each candidate module:

EXECUTE:

python3 .plan/execute-script.py plan-marshall:analyze-project-architecture:architecture module \
  --name {module}

Document Selection Reasoning

Template: templates/module-selection-analysis.md (force load)

Step 5: Determine Package Placement

For each selected module, determine where new code belongs.

Load Complete Package Structure

EXECUTE:

python3 .plan/execute-script.py plan-marshall:analyze-project-architecture:architecture module \
  --name {module} --full

Package Selection Decision Matrix

Detail: See standards/module-selection.md for key_packages guidance and validation checklist.

Document Package Reasoning

Template: templates/package-selection.md (force load)

Step 6: Create Deliverables with Skills by Profile

Create deliverables with module context and skills organized by profile.

Core constraint: One deliverable = one module.

Check Module Test Infrastructure

EXECUTE:

python3 .plan/execute-script.py plan-marshall:analyze-project-architecture:architecture modules \
  --command module-tests

Returns list of module names that have unit test infrastructure.

Skills by Profile Block

• skills-implementation: Always included
• skills-testing: Only if module has test infrastructure

Detail: See standards/skills-by-profile.md for profile design rationale and task-plan integration.

Deliverable Structure

Contract: pm-workflow:manage-solution-outline/standards/deliverable-contract.md (force load)

Each deliverable MUST include all required fields from the contract:

• Metadata (change_type, execution_mode, domain, depends)
• Module Context (module, package, placement_rationale)
• Skills by Profile (skills-implementation; skills-testing if test infra exists)
• Affected files (explicit list)
• Verification (command and criteria)

Step 7: Create IT Deliverable (Optional)

If integration tests are needed, create a separate deliverable targeting the IT module.

When to Create IT Deliverable

Check IT Infrastructure

EXECUTE:

python3 .plan/execute-script.py plan-marshall:analyze-project-architecture:architecture modules \
  --command integration-tests

If result is empty: Skip IT deliverable (no IT module exists).

Detail: See standards/integration-tests.md for IT decision flow, module patterns, and verification commands.

IT Deliverable Structure

IT deliverables follow the same contract as implementation deliverables.

Contract: pm-workflow:manage-solution-outline/standards/deliverable-contract.md

Key Differences:

• IT is always a separate deliverable - not embedded in implementation deliverable
• IT targets the IT module - found via architecture modules --command integration-tests
• IT depends on implementation - set depends: to reference the implementation deliverable
• IT has only skills-implementation - IT code is "implementation" of test code

Step 8: Write Solution Document

Write the solution document using heredoc.

Skill: pm-workflow:manage-solution-outline (force load)

Provides complete guidance on solution document structure, diagram patterns, and examples by task type.

EXECUTE:

python3 .plan/execute-script.py pm-workflow:manage-solution-outline:manage-solution-outline \
  write \
  --plan-id {plan_id} <<'EOF'
{content per manage-solution-outline skill with deliverables per deliverable-contract.md}
EOF

Validation runs automatically on every write.

Step 9: Set Detected Domains

EXECUTE:

python3 .plan/execute-script.py pm-workflow:manage-config:manage-config set-domains \
  --plan-id {plan_id} --domains {detected_domains}

This is an intelligent decision output - not a copy of marshal.json domains, but Claude's analysis of which domains are relevant to the specific request.

Step 10: Record Issues as Lessons

EXECUTE:

python3 .plan/execute-script.py plan-marshall:lessons-learned:manage-lesson add \
  --component-type skill \
  --component-name phase-refine-outline \
  --category observation \
  --title "{issue summary}" \
  --detail "{context and resolution approach}"

Step 11: Return Results

Return structured output:

status: success
plan_id: {plan_id}
deliverable_count: {N}
domains_detected: [{detected_domains}]
lessons_recorded: {count}
message: {error message if status=error}

Error Handling

Integration

Invoked by: pm-workflow:solution-outline-agent (thin agent)

Script Notations (use EXACTLY as shown):

• plan-marshall:analyze-project-architecture:architecture - Architecture queries
• pm-workflow:manage-solution-outline:manage-solution-outline - Write solution document
• pm-workflow:manage-plan-documents:manage-plan-documents - Request operations
• pm-workflow:manage-config:manage-config - Plan config operations
• pm-workflow:manage-references:manage-references - Plan references
• plan-marshall:lessons-learned:manage-lesson - Record lessons on issues

Consumed By:

• pm-workflow:task-plan skill (reads deliverables for task creation)

Output Validation

The workflow skill MUST validate that each deliverable contains all required fields from the deliverable contract:

• change_type metadata
• execution_mode metadata
• domain metadata (valid domain from marshal.json)
• depends field (none or valid deliverable references)
• Module context (module, package, placement_rationale)
• Skills by Profile (skills-implementation always; skills-testing if module has test infra)
• Explicit file list (not "all files matching X")
• Verification command and criteria

Related Documents

• pm-workflow:plan-wf-skill-api/standards/solution-outline-skill-contract.md - Contract this skill implements
• pm-workflow:manage-solution-outline/standards/deliverable-contract.md - Deliverable structure
• pm-workflow:pm-workflow-architecture - Workflow architecture overview
• plan-marshall:analyze-project-architecture - Architecture API documentation
• plan-marshall:analyze-project-architecture/standards/module-graph-format.md - Module dependency graph format