Manage Solution Outline Skill

This skill provides structure guidelines, examples, and operations for

solution_outline.md

When to Load This Skill

Load this skill in Step 0 when:

• Creating a solution outline (via

  solution-outline-agent

  thin agent)
• Reviewing or updating an existing solution outline
• Validating solution document structure

First action: Load

plan-marshall:analyze-project-architecture

Not needed for: Creating tasks from deliverables (use manage-tasks skill)

Document Structure

Solution outlines have a fixed structure with required and optional sections:

# Solution: {title}

plan_id: {plan_id}
created: {timestamp}
compatibility: {value} — {long description}

## Summary          ← REQUIRED: 2-3 sentences describing the approach

## Overview         ← REQUIRED: ASCII diagram showing architecture/flow

## Deliverables     ← REQUIRED: Numbered ### sections

## Approach         ← OPTIONAL: Execution strategy

## Dependencies     ← OPTIONAL: External requirements

## Risks and Mitigations  ← OPTIONAL: Risk analysis

See standards/structure.md for detailed requirements.

Deliverables Format

Deliverables use numbered

###

## Deliverables

### 1. Create JwtValidationService class

Description of what this deliverable produces.

**Location**: `src/main/java/de/cuioss/auth/jwt/JwtValidationService.java`

**Responsibilities**:
- Validate JWT signature
- Check token expiration

### 2. Add configuration support

Description...

Key Rules:

• Numbers must be sequential starting from 1
• Titles should be concrete work items (not abstract goals)
• Each deliverable should be independently achievable
• Include location, responsibilities, or success criteria

See standards/deliverables.md for reference format.

Overview Diagrams

The Overview section contains ASCII diagrams showing component relationships. Different task types use different diagram patterns:

See standards/diagrams.md for patterns and examples.

Examples by Task Type

Examples provide starting points for different task categories:

Writing the Solution Document

Step 0: Load Project Architecture

Load project architecture knowledge via the

plan-marshall:analyze-project-architecture

Skill: plan-marshall:analyze-project-architecture

Then query module information:

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

Use the returned structure for:

modules.{name}.responsibility

modules.{name}.purpose

modules.{name}.key_packages

modules.{name}.skills_by_profile

modules.{name}.tips

modules.{name}.insights

internal_dependencies

Step 1: Analyze Request

Read the request document to understand:

• What is being requested
• Scope and constraints
• Success criteria

Step 2: Design Architecture

Before writing, determine:

• Components involved
• Dependencies between components
• Execution order

Step 3: Create Diagram

Draw ASCII diagram showing:

• New components (boxed)
• Existing components (labeled)
• Dependencies (arrows)
• Package/file structure

Step 4: Write and Validate Document

Write using stdin with validation to handle ASCII box-drawing characters:

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

## Summary
...

## Overview

┌─────────────┐ │ Component │ └─────────────┘

## Deliverables
...
EOF

Parameters:

• --plan-id

  (required): Plan identifier

• --force

  : Overwrite existing solution outline

Note: Validation runs automatically on write - checks for required sections (Summary, Overview, Deliverables) and numbered deliverable format (

### N. Title

Why heredoc? Solution outlines contain ASCII diagrams with box-drawing characters (│, ─, ┌, └). Using

<<'EOF'

Deliverable References

When tasks reference deliverables, use the full reference format:

deliverable: "1. Create JwtValidationService class"

Reference Format Rules:

• Include number and full title
• Format:

  N. Title

  (number, dot, space, title)
• Title must match exactly what's in solution document

Validation:

python3 .plan/execute-script.py pm-workflow:manage-solution-outline:manage-solution-outline \
  list-deliverables \
  --plan-id {plan_id}

Integration

Loaded by:

• pm-workflow:solution-outline-agent

  (thin agent that loads domain skills from references.toon)
• Domain skills:

  pm-plugin-development:ext-outline-plugin

  , etc.

Data Sources (via skills):

• plan-marshall:analyze-project-architecture

  - Project architecture knowledge (modules, responsibilities, packages)

• marshal.json

  - Module domains for skill routing
• Request document - What is being requested

Scripts Used:

Script:

pm-workflow:manage-solution-outline:manage-solution-outline

write

--plan-id [--force]

validate

--plan-id

read

--plan-id [--raw] [--deliverable-number N]

list-deliverables

--plan-id

exists

--plan-id

Related Skills:

• plan-marshall:analyze-project-architecture

  - Project architecture knowledge (load in Step 0)

• pm-workflow:manage-tasks

  - Task creation with deliverable references

• pm-workflow:manage-plan-documents

  - Request document operations

Script Output Examples

write

Output (TOON):

status: success
plan_id: my-feature
file: solution_outline.md
action: created
validation:
  deliverable_count: 3
  sections_found: summary,overview,deliverables
  compatibility: breaking — Clean-slate approach, no deprecation nor transitionary comments

validate

Output (TOON):

status: success
plan_id: my-feature
file: solution_outline.md
validation:
  sections_found: summary,overview,deliverables
  deliverable_count: 3
  deliverables:
    - 1. Create JwtValidationService class
    - 2. Add configuration support
    - 3. Create unit tests
  compatibility: breaking — Clean-slate approach, no deprecation nor transitionary comments

list-deliverables

Output (TOON):

status: success
plan_id: my-feature
deliverable_count: 3
deliverables:
  - number: 1
    title: Create JwtValidationService class
    reference: 1. Create JwtValidationService class
  - number: 2
    title: Add configuration support
    reference: 2. Add configuration support

read

Output (TOON):

status: success
plan_id: my-feature
file: solution_outline.md
content:
  _header: # Solution: JWT Validation...
  summary: Implement JWT validation service...
  overview: Component architecture diagram...
  deliverables: ### 1. Create JwtValidationService...

With

--raw

With

--deliverable-number N

Example: Read deliverable 3:

python3 .plan/execute-script.py pm-workflow:manage-solution-outline:manage-solution-outline read \
  --plan-id {plan_id} \
  --deliverable-number 3

Output (TOON):

status: success
plan_id: my-feature
deliverable:
  number: 3
  title: Implement unit tests
  reference: 3. Implement unit tests
  metadata:
    change_type: create
    execution_mode: automated
    domain: java
    module: jwt-service
    depends: 1
  profiles:
    - testing
  affected_files:
    - src/test/java/de/cuioss/jwt/JwtValidationServiceTest.java

If deliverable not found, returns error with available numbers:

status: error
error: deliverable_not_found
plan_id: my-feature
number: 999
available:
  - 1
  - 2
  - 3

exists

Output (TOON):

status: success
plan_id: my-feature
file: solution_outline.md
exists: true

Returns exit code 0 if exists, 1 if not.