cuioss/manage-solution-outline

Manage Solution Outline Skill

This skill provides structure guidelines, examples, and operations for solution_outline.md documents. Load this skill when creating or modifying solution outlines.

Enforcement

Base contract: See manage-contract.md for shared enforcement rules, TOON output format, and error response patterns.

Skill-specific constraints:

• Use Write tool for document content, then validate via script (not the script API write path)
• Do not skip validation after writing or updating solution content
• Document creation follows the resolve-path, Write, validate pattern
• Deliverable numbering must be sequential starting from 1

Document Structure

Required sections: Solution Metadata (top-level ## Solution Metadata block with scope_estimate), Summary (2-3 sentences), Overview (ASCII diagram), Deliverables (numbered ### sections). Optional: Approach, Dependencies, Risks and Mitigations.

See standards/solution-outline-standard.md for the complete section specification, content guidelines, and validation rules.

Solution Metadata Field: scope_estimate

scope_estimate is a solution-level field (not per-deliverable) that classifies the change footprint. It powers downstream Q-Gate bypass and execution-manifest decisions.

| Value | Meaning | |-------|---------| | none | Pure analysis — no affected files | | surgical | ≤3 files in a single module, no public API surface | | single_module | ≤10 files in one module | | multi_module | Touches more than one module | | broad | Codebase-wide / glob-only changes |

The script read and get-field APIs expose the persisted value. write/update reject the document if scope_estimate is missing or not in the enum above.

---

Deliverables Format

Deliverables use numbered ### headings:

## 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/solution-outline-standard.md for reference format.

---

Overview Diagrams

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

| Task Type | Diagram Style | |-----------|---------------| | Feature | Component/class relationships with dependencies | | Refactoring | BEFORE → AFTER transformation comparison | | Bugfix | Problem sequence + Solution architecture | | Documentation | File structure with cross-references | | Plugin | Integration flow with build phases |

See standards/solution-outline-standard.md for patterns and examples.

---

Examples by Task Type

Examples provide starting points for different task categories:

| Example | Use When | |---------|----------| | examples/java-feature.md | Java feature implementation | | examples/javascript-feature.md | JavaScript/frontend feature | | examples/plugin-feature.md | Marketplace plugin development | | examples/refactoring.md | Code refactoring tasks | | examples/bugfix.md | Bug fix with root cause analysis | | examples/documentation-task.md | Documentation creation/updates |

---

Authoring Workflow

See standards/authoring-guide.md for the step-by-step workflow for writing a solution document (load architecture, analyze request, design, create diagram, write and validate).

---

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 plan-marshall:manage-solution-outline:manage-solution-outline \
  list-deliverables \
  --plan-id {plan_id}

---

Canonical invocations

The canonical argparse surface for manage-solution-outline.py. The D4 plugin-doctor analyzer (_analyze_manage_invocation.py) reads this section as source-of-truth for markdown notation occurrences across the marketplace. Consuming skills xref this section by name (e.g., "see manage-solution-outline Canonical invocations → resolve-path") instead of restating the command inline.

validate

python3 .plan/execute-script.py plan-marshall:manage-solution-outline:manage-solution-outline validate \
  --plan-id PLAN_ID

list-deliverables

python3 .plan/execute-script.py plan-marshall:manage-solution-outline:manage-solution-outline list-deliverables \
  --plan-id PLAN_ID

read

python3 .plan/execute-script.py plan-marshall:manage-solution-outline:manage-solution-outline read \
  --plan-id PLAN_ID [--raw] \
  [--deliverable-number N | --section SECTION]

--deliverable-number and --section are mutually exclusive.

exists

python3 .plan/execute-script.py plan-marshall:manage-solution-outline:manage-solution-outline exists \
  --plan-id PLAN_ID

get-field

python3 .plan/execute-script.py plan-marshall:manage-solution-outline:manage-solution-outline get-field \
  --plan-id PLAN_ID --field FIELD

Supported --field values: scope_estimate.

resolve-path

python3 .plan/execute-script.py plan-marshall:manage-solution-outline:manage-solution-outline resolve-path \
  --plan-id PLAN_ID

write

python3 .plan/execute-script.py plan-marshall:manage-solution-outline:manage-solution-outline write \
  --plan-id PLAN_ID [--force]

update

python3 .plan/execute-script.py plan-marshall:manage-solution-outline:manage-solution-outline update \
  --plan-id PLAN_ID

get-module-context

python3 .plan/execute-script.py plan-marshall:manage-solution-outline:manage-solution-outline get-module-context \
  [--project-dir DIR | --plan-id PLAN_ID]

--project-dir (default .) and --plan-id are mutually exclusive routing flags.

---

Error Responses

See manage-contract.md for the standard error response format.

| Error Code | Cause | |------------|-------| | file_not_found | solution_outline.md doesn't exist | | document_not_found | Same as file_not_found (used by update command) | | parse_error | Failed to parse document structure | | validation_failed | Missing required sections (Solution Metadata, Summary, Overview, or Deliverables), missing scope_estimate, invalid scope_estimate enum value, or deliverable numbering not sequential | | field_not_found | get-field requested a field that is not persisted (e.g., scope_estimate absent) | | unknown_field | get-field requested an unsupported field name | | deliverable_not_found | Requested deliverable number doesn't exist (read with --deliverable-number) | | section_not_found | Requested section doesn't exist (read with --section) |

See also standards/solution-outline-standard.md for deliverable validation criteria used during task planning.

Integration

Loaded by:

• plan-marshall:phase-3-outline skill (loads domain skills from references.json)
• Domain skills: pm-plugin-development:ext-outline-workflow, etc.

Data Sources (via skills):

• plan-marshall:manage-architecture - Project architecture knowledge (modules, responsibilities, packages)
• marshal.json - Module domains for skill routing
• Request document - What is being requested

Scripts Used:

Script: plan-marshall:manage-solution-outline:manage-solution-outline

| Command | Parameters | Description | |---------|------------|-------------| | resolve-path | --plan-id | Get target file path (returns path: .plan/plans/{plan_id}/solution_outline.md) | | write | --plan-id | Validate newly created solution on disk; sets action: created. Returns file_exists error if file was already validated via write before — use update instead. | | update | --plan-id | Validate updated solution on disk; sets action: updated. Returns document_not_found if file doesn't exist — use write for initial creation. | | validate | --plan-id | Validate structure | | read | --plan-id [--raw] [--deliverable-number N \| --section NAME] | Read solution, specific deliverable, or a single top-level section | | get-field | --plan-id --field NAME | Read a single solution-level metadata field. Currently supported: scope_estimate. Returns field_not_found when absent. | | list-deliverables | --plan-id | Extract deliverables list | | exists | --plan-id | Check if solution exists |

Related Skills:

• plan-marshall:manage-architecture - Project architecture knowledge (load in Step 0)
• plan-marshall:manage-tasks - Task creation with deliverable references
• plan-marshall: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: solution_metadata,summary,overview,deliverables
  compatibility: breaking — Clean-slate approach, no deprecation nor transitionary comments
  scope_estimate: surgical

update

Output (TOON) — same as write but action is always updated:

status: success
plan_id: my-feature
file: solution_outline.md
action: updated
validation:
  deliverable_count: 3
  sections_found: solution_metadata,summary,overview,deliverables
  scope_estimate: surgical

Returns error document_not_found if solution outline does not exist (use write to create first).

validate

Output (TOON):

status: success
plan_id: my-feature
file: solution_outline.md
validation:
  sections_found: solution_metadata,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
  scope_estimate: surgical

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...
  solution_metadata: scope_estimate: surgical
  summary: Implement JWT validation service...
  overview: Component architecture diagram...
  deliverables: ### 1. Create JwtValidationService...
scope_estimate: surgical

With --raw: Returns raw markdown content.

With --deliverable-number N: Returns a specific deliverable by number.

Example: Read deliverable 3:

python3 .plan/execute-script.py plan-marshall: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: feature
    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

With --section NAME: Returns a single top-level ## Section body. The name is case-insensitive; spaces are normalized to underscores (so --section "Risks and Mitigations" matches ## Risks and Mitigations). Mutually exclusive with --deliverable-number. Compatible with --raw — when combined, prints just the section body to stdout.

Example: Read the Summary section:

python3 .plan/execute-script.py plan-marshall:manage-solution-outline:manage-solution-outline read \
  --plan-id {plan_id} \
  --section summary

Output (TOON):

status: success
plan_id: my-feature
file: solution_outline.md
section: summary
requested_section: summary
content: Implement JWT validation service for the authentication module...

If the section does not exist, returns:

status: error
error: section_not_found
plan_id: my-feature
requested_section: nonexistent
message: "Section 'nonexistent' not found in solution_outline.md"

get-field

Output (TOON) — example for scope_estimate:

status: success
plan_id: my-feature
file: solution_outline.md
field: scope_estimate
value: surgical

If the field is absent from the document:

status: error
error: field_not_found
plan_id: my-feature
field: scope_estimate

If the field name is not supported:

status: error
error: unknown_field
plan_id: my-feature
field: foo

exists

Output (TOON):

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

Returns exit code 0 if exists, 1 if not.

---

Related

• manage-tasks — Consumes deliverables from solution outline for task creation
• manage-architecture — Provides module placement data used during outline creation
• manage-references — Tracks affected_files identified during outline phase
• manage-plan-documents — Stores the request document that drives the outline