Phase Outline Skill

Role: Two-track workflow skill for creating solution outlines. Routes based on track selection from phase-2-refine.

Prerequisite: Request must be refined (phase-2-refine completed) with track field set.

Two-Track Design

Track	When Used	Approach
Simple	Localized changes (single_file, single_module, few_files)	Direct deliverable creation from module_mapping
Complex	Codebase-wide changes (multi_module, codebase_wide)	Load domain skill for discovery/analysis

Track determined by: phase-2-refine (stored in references.json)

Input Parameters

Parameter	Type	Required	Description
`plan_id`	string	Yes	Plan identifier

Workflow Overview

code

Step 1: Load Inputs → Step 1.5: Detect Change Type → Step 2: Route by Track → {Simple: Steps 3-5 | Complex: Steps 6-9} → Step 10: Return

Step 1: Load Inputs

Purpose: Load track, request, compatibility, and context from phase-2-refine output and sinks.

Note: This skill receives track, track_reasoning, scope_estimate, compatibility, and compatibility_description from the phase-2-refine return output. These values are passed as input parameters.

1.1 Receive Track from Phase-2-Refine Output

The track value (simple | complex) is received from the phase-2-refine return output, not read from references.json.

If track not provided in input, extract from decision.log:

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  read --plan-id {plan_id} --type decision | grep "(pm-workflow:phase-2-refine) Track:"

Parse the output to extract track value from: (pm-workflow:phase-2-refine) Track: {track} - {reasoning}

1.2 Read Request

Read request (automatically uses clarified_request if available, otherwise body):

bash

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

1.3 Read Module Mapping

Read from work directory (persisted by phase-2-refine):

bash

python3 .plan/execute-script.py pm-workflow:manage-files:manage-files read \
  --plan-id {plan_id} \
  --file work/module_mapping.toon

1.4 Read Domains

bash

python3 .plan/execute-script.py pm-workflow:manage-references:manage-references get \
  --plan-id {plan_id} --field domains

1.5 Receive Compatibility from Phase-2-Refine Output

The compatibility and compatibility_description values are received from the phase-2-refine return output.

If compatibility not provided in input, read from marshal.json:

bash

python3 .plan/execute-script.py plan-marshall:manage-plan-marshall-config:plan-marshall-config \
  plan phase-2-refine get --field compatibility --trace-plan-id {plan_id}

Store as compatibility and derive compatibility_description from the value:

•breaking → "Clean-slate approach, no deprecation nor transitionary comments"
•deprecation → "Add deprecation markers to old code, provide migration path"
•smart_and_ask → "Assess impact and ask user when backward compatibility is uncertain"

1.6 Log Context (to work.log - status, not decision)

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  work {plan_id} INFO "[STATUS] (pm-workflow:phase-3-outline) Starting outline: track={track}, domains={domains}, compatibility={compatibility}"

Step 1.5: Detect Change Type

Purpose: Determine the change type for agent routing.

1.5.1 Spawn Detection Agent

code

Task: pm-workflow:detect-change-type-agent
  Input:
    plan_id: {plan_id}

Agent Output (TOON):

toon

status: success
plan_id: {plan_id}
change_type: enhancement
confidence: 90
reasoning: "Request describes improving existing functionality"

1.5.2 Read Detected Change Type

The agent persists change_type to status.toon metadata. Read it:

bash

python3 .plan/execute-script.py pm-workflow:plan-marshall:manage-lifecycle get-metadata \
  --plan-id {plan_id} \
  --field change_type

1.5.3 Log Detection

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  decision {plan_id} INFO "(pm-workflow:phase-3-outline) Change type: {change_type} (confidence: {confidence})"

Step 2: Route by Track

Based on track from Step 1.1:

code

IF track == "simple":
  → Execute Simple Track (Steps 3-5)
ELSE:  # track == "complex"
  → Execute Complex Track (Steps 6-9)

Simple Track (Steps 3-5)

For localized changes where targets are already known from module_mapping.

Step 3: Validate Targets

Purpose: Verify target files/modules exist and match domain.

3.1 Validate Target Files Exist

For each target in module_mapping:

bash

# For file targets
ls -la {target_path}

If target doesn't exist, ERROR: "Target not found: {target}"

3.2 Log Validation

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  decision {plan_id} INFO "(pm-workflow:phase-3-outline) Validated {N} targets in {domain}"

Step 4: Create Deliverables

Purpose: Direct mapping from module_mapping to deliverables.

4.1 Build Deliverables from Module Mapping

For each entry in module_mapping:

•Determine change_type from request (create, modify, migrate, refactor)
•Determine execution_mode (automated)
•Map domain from references.json
•Use module from module_mapping

4.2 Deliverable Structure

Use template from pm-workflow:manage-solution-outline/templates/deliverable-template.md:

markdown

### {N}. {Action Verb} {Component Type}: {Name}

**Metadata:**
- change_type: {feature|enhancement|tech_debt|bug_fix}
- execution_mode: automated
- domain: {domain}
- module: {module}
- depends: none

**Profiles:**
- implementation
- testing (if module has test infrastructure)

**Affected files:**
- `{explicit/path/to/file1}`
- `{explicit/path/to/file2}`

**Change per file:** {What will be created or modified}

**Verification:**
- Command: {verification command}
- Criteria: {success criteria}

**Success Criteria:**
- {Specific criterion 1}
- {Specific criterion 2}

4.3 Log Deliverable Creation

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  decision {plan_id} INFO "(pm-workflow:phase-3-outline) Created deliverable for {target}"

Step 5: Simple Q-Gate

Purpose: Lightweight verification for simple track.

5.1 Verify Deliverables

For each deliverable:

•Target exists? - Already validated in Step 3
•Deliverable aligns with request intent? - Compare deliverable scope with request

5.2 Log Q-Gate Result

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  decision {plan_id} INFO "(pm-workflow:phase-3-outline:qgate) Simple: Deliverable {N}: pass"

→ Continue to Step 10 (Write Solution and Return)

Complex Track (Steps 6-9)

For codebase-wide changes requiring discovery and analysis.

Step 6: Resolve Change-Type Agent

Purpose: Find the appropriate agent for the detected change type and domain.

6.1 Resolve Agent

For the primary domain in references.json:

bash

python3 .plan/execute-script.py plan-marshall:manage-plan-marshall-config:plan-marshall-config \
  resolve-change-type-agent --domain {domain} --change-type {change_type} --trace-plan-id {plan_id}

Output (TOON):

toon

status: success
domain: {domain}
change_type: {change_type}
agent: pm-plugin-development:change-feature-outline-agent  # or generic fallback

Fallback: If no domain-specific agent configured, use generic: pm-workflow:change-{change_type}-agent

6.2 Log Resolution

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  decision {plan_id} INFO "(pm-workflow:phase-3-outline) Resolved agent: {agent_notation}"

Step 7: Spawn Change-Type Agent

Purpose: Spawn the resolved agent to handle discovery, analysis, and deliverable creation.

7.1 Spawn Agent

code

Task: {resolved_agent_notation}
  Input:
    plan_id: {plan_id}

The agent handles the complete Complex Track workflow internally:

•Discovery (spawning inventory agent if needed)
•Analysis (spawning component agents if needed)
•Persist assessments → assessments.jsonl
•Confirm uncertainties with user
•Group into deliverables
•Write solution_outline.md (must include compatibility: {value} — {description} in header metadata)

7.2 Log Agent Spawn

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  decision {plan_id} INFO "(pm-workflow:phase-3-outline) Spawned {agent} for {domain}"

Step 8: Agent Completion

Purpose: Agent returns minimal status; data is in sinks.

8.1 Agent Return Value

toon

status: success
plan_id: {plan_id}
deliverable_count: {N}
change_type: {change_type}

8.2 Log Agent Completion

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  decision {plan_id} INFO "(pm-workflow:phase-3-outline) Agent complete: {deliverable_count} deliverables"

If agent returns error: HALT and return error.

Step 9: Q-Gate Verification

Purpose: Verify skill output meets quality standards.

9.1 Spawn Q-Gate Agent

code

Task: pm-workflow:q-gate-validation-agent
  Input:
    plan_id: {plan_id}

Q-Gate reads from:

•solution_outline.md (written by domain skill)
•artifacts/assessments.jsonl (written by domain skill)
•request.md (clarified_request or body)

Q-Gate verifies:

•Each deliverable fulfills request intent
•Deliverables respect architecture constraints
•No false positives (files that shouldn't be changed)
•No missing coverage (files that should be changed but aren't)

Q-Gate writes:

•artifacts/findings.jsonl - Any triage findings
•logs/decision.log - Q-Gate verification results

9.2 Q-Gate Return Value

toon

status: success
plan_id: {plan_id}
deliverables_verified: {N}
passed: {count}
flagged: {count}

9.3 Log Q-Gate Result

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  decision {plan_id} INFO "(pm-workflow:phase-3-outline:qgate) Full: {passed} passed, {flagged} flagged"

9.4 Handle Q-Gate Corrections (if flagged > 0)

If Q-Gate flagged false positives or missing coverage:

•Update solution_outline.md with corrections using --force:

bash

python3 .plan/execute-script.py pm-workflow:manage-solution-outline:manage-solution-outline write \
  --plan-id {plan_id} --force <<'EOF'
{corrected solution document}
EOF

•Update references (e.g., remove false positives from modified_files):

bash

python3 .plan/execute-script.py pm-workflow:manage-references:manage-references set-list \
  --plan-id {plan_id} --field modified_files --values "{corrected file list}"

•Log the correction:

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  work {plan_id} INFO "[ARTIFACT] (pm-workflow:phase-3-outline) Updated solution_outline.md - {correction reason}"

→ Continue to Step 10

Generic Workflow (No Domain-Specific Agent)

For domains without domain-specific change-type agents, the generic agents in pm-workflow are used. These generic agents (e.g., pm-workflow:change-feature-agent) provide baseline behavior.

Generic Step A: Read Module Mapping

Module mapping from phase-2-refine specifies target modules.

bash

python3 .plan/execute-script.py pm-workflow:manage-references:manage-references get \
  --plan-id {plan_id} --field module_mapping

Generic Step B: Create Deliverables per Module

For each module in module_mapping:

•Create deliverable with appropriate profile
•No discovery needed - modules already identified in phase-2-refine

Check Module Test Infrastructure

bash

python3 .plan/execute-script.py plan-marshall:analyze-project-architecture:architecture modules \
  --command module-tests \
  --trace-plan-id {plan_id}

Use result to determine if testing profile applies.

Deliverable Structure

Use same template as Simple Track (Step 4.2).

Generic Step C: Write Solution Outline

bash

python3 .plan/execute-script.py pm-workflow:manage-solution-outline:manage-solution-outline write \
  --plan-id {plan_id} <<'EOF'
{solution document with deliverables}
EOF

Generic Step D: Log Completion

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  decision {plan_id} INFO "(pm-workflow:phase-3-outline) Generic workflow: {N} deliverables"

→ Continue to Step 10

Step 10: Write Solution and Return

Step 10.1: Write Solution Document (Simple Track only)

For Simple Track, write solution_outline.md:

bash

python3 .plan/execute-script.py pm-workflow:manage-solution-outline:manage-solution-outline write \
  --plan-id {plan_id} <<'EOF'
# Solution: {title}

plan_id: {plan_id}
compatibility: {compatibility} — {compatibility_description}

## Summary

{2-3 sentence summary of the solution}

## Overview

{ASCII diagram showing solution structure}

## Deliverables

{deliverables from Step 4}
EOF

Note: Complex Track - skill already wrote solution_outline.md in Step 7.

Step 10.2: Log Completion

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  work {plan_id} INFO "[ARTIFACT] (pm-workflow:phase-3-outline) Created solution_outline.md"

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  decision {plan_id} INFO "(pm-workflow:phase-3-outline) Complete: {N} deliverables, Q-Gate: {pass/fail}"

Step 10.3: Return Results

Return minimal status - all data is in sinks:

toon

status: success
plan_id: {plan_id}
track: {simple|complex}
deliverable_count: {N}
qgate_passed: {true|false}

Error Handling

Scenario	Action
Track not set	Return `{status: error, message: "phase-2-refine incomplete - track not set"}`
Target not found (Simple)	Return error with invalid target
Change type not detected	Return `{status: error, message: "detect-change-type-agent failed to determine change type"}`
Agent not found	Fall back to generic: `pm-workflow:change-{change_type}-agent`
Agent fails (Complex)	Return error, do not fall back
Q-Gate fails	Return with `qgate_passed: false` and findings
Request not found	Return `{status: error, message: "Request not found"}`

CRITICAL: If Complex Track agent fails, do NOT fall back to grep/search. Fail clearly.

Integration

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

Script Notations (use EXACTLY as shown):

•pm-workflow:manage-files:manage-files - Read module_mapping from work/module_mapping.toon
•pm-workflow:manage-plan-documents:manage-plan-documents - Read request
•pm-workflow:manage-references:manage-references - Read domains
•pm-workflow:manage-solution-outline:manage-solution-outline - Write solution document
•pm-workflow:plan-marshall:manage-lifecycle - Read/write change_type metadata
•plan-marshall:manage-plan-marshall-config:plan-marshall-config - Resolve change-type agent, read compatibility (fallback)
•plan-marshall:manage-logging:manage-log - Decision and work logging

Spawns (Complex Track):

•pm-workflow:detect-change-type-agent (Step 1.5 - change type detection)
•Change-type agent (e.g., pm-plugin-development:change-feature-outline-agent or pm-workflow:change-feature-agent)
•pm-workflow:q-gate-validation-agent (Q-Gate verification)

Consumed By:

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

Phase Outline Skill

Two-Track Design

Input Parameters

Workflow Overview

Step 1: Load Inputs

1.1 Receive Track from Phase-2-Refine Output

1.2 Read Request

1.3 Read Module Mapping

1.4 Read Domains

1.5 Receive Compatibility from Phase-2-Refine Output

1.6 Log Context (to work.log - status, not decision)

Step 1.5: Detect Change Type

1.5.1 Spawn Detection Agent

1.5.2 Read Detected Change Type

1.5.3 Log Detection

Step 2: Route by Track

Simple Track (Steps 3-5)

Step 3: Validate Targets

3.1 Validate Target Files Exist

3.2 Log Validation

Step 4: Create Deliverables

4.1 Build Deliverables from Module Mapping

4.2 Deliverable Structure

4.3 Log Deliverable Creation

Step 5: Simple Q-Gate

5.1 Verify Deliverables

5.2 Log Q-Gate Result

Complex Track (Steps 6-9)

Step 6: Resolve Change-Type Agent

6.1 Resolve Agent

6.2 Log Resolution

Step 7: Spawn Change-Type Agent

7.1 Spawn Agent

7.2 Log Agent Spawn

Step 8: Agent Completion

8.1 Agent Return Value

8.2 Log Agent Completion

Step 9: Q-Gate Verification

9.1 Spawn Q-Gate Agent

9.2 Q-Gate Return Value

9.3 Log Q-Gate Result

9.4 Handle Q-Gate Corrections (if flagged > 0)

Generic Workflow (No Domain-Specific Agent)

Generic Step A: Read Module Mapping

Generic Step B: Create Deliverables per Module

Check Module Test Infrastructure

Deliverable Structure

Generic Step C: Write Solution Outline

Generic Step D: Log Completion

Step 10: Write Solution and Return

Step 10.1: Write Solution Document (Simple Track only)

Step 10.2: Log Completion

Step 10.3: Return Results

Error Handling

Integration

Related Documents