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

plan_id

feedback

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 2.5: Load outline extension skills (if domain has one)     │
│          → resolve-workflow-skill-extension --type outline       │
│          → Extensions provide Domain Constraints, Patterns       │
│                                                                  │
│  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

Step 2.5: Load Outline Extension Skills

For each domain in config.toon, check if an outline extension exists and load it as context.

Purpose: Outline extensions provide domain-specific knowledge (Domain Constraints, Deliverable Patterns) that augment the standard workflow. They are skills loaded as context, not workflow replacements.

For each domain from Step 2:

EXECUTE:

python3 .plan/execute-script.py plan-marshall:plan-marshall-config:plan-marshall-config \
  resolve-workflow-skill-extension --domain {domain} --type outline

Output (TOON):

status: success
domain: {domain}
type: outline
extension: pm-plugin-development:ext-outline-plugin  # or null if no extension

If extension exists (not null), load it as context:

Skill: {resolved_extension}

The extension skill provides:

• Domain Constraints: Rules for deliverable creation (component rules, dependency rules)
• Deliverable Patterns: Grouping strategies, file structures, verification commands
• Impact Analysis Patterns: Discovery commands for cross-cutting changes

These are applied naturally during deliverable creation (Steps 4-6) - no special processing needed.

If no extension exists: Continue with standard workflow. Most domains (java, javascript) don't need outline extensions.

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

Detail: See

standards/module-selection.md

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

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

Document Package Reasoning

Template:

templates/package-selection.md

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

Deliverable Structure

Contract:

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

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

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

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-2-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

{status: error, message: "Run /marshall-steward first"}

{status: error, message: "Request not found"}

Integration

Invoked by:

pm-workflow:solution-outline-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:phase-3-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:workflow-extension-api/standards/extensions/outline-extension.md

  - Outline extension contract

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

  - Deliverable structure

• pm-workflow: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