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, Lessons Consulted.

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.

get-deliverable

python3 .plan/execute-script.py plan-marshall:manage-solution-outline:manage-solution-outline get-deliverable \
  --plan-id PLAN_ID --deliverable-number N

Equivalent to the read --deliverable-number N read-verb form: both funnel through the same shared lookup and return byte-identical output. get-deliverable shares the deliverable_not_found / document_not_found error contract with read --deliverable-number (no new error code is introduced).

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.

Output (TOON):

status: success
project_dir: /path/to/checkout
worktree_fallback: false
module_count: 2
modules[2]{name,path,purpose,responsibility}:
  default,.,Root project module,Project-wide responsibilities
  plan-marshall,marketplace/bundles/plan-marshall,Workflow orchestration,Plan lifecycle

Each modules[] entry additionally carries key_packages, tips, insights, best_practices, and skills_by_profile when the module's enriched architecture store populates them. The hint fields (tips, insights, best_practices) are presence-gated — each is emitted only when the corresponding enriched.json array is non-empty, and omitted entirely otherwise. Consumers (e.g. phase-3-outline rendering the ## Architecture Hints section) read these fields directly off each module entry.

Read provenance — project_dir and worktree_fallback ride on every payload returned after project-directory routing has resolved (success, not_found, and handler-level error alike), so the reported context always names the checkout it came from. The one payload that carries neither is the mutually_exclusive_args routing error: it is emitted before a project directory has been resolved, so there is no checkout for it to name.

Field	Meaning
project_dir	The directory the architecture data was actually read from.
worktree_fallback	true only when --plan-id named a plan whose worktree could not be resolved and the read degraded to the cwd-relative checkout root.
worktree_fallback_reason	Emitted only when worktree_fallback is true; names the resolution failure verbatim.

The fallback exists because a plan declaring use_worktree=true has no materialized worktree until phase-5-execute, while phase-3-outline — the phase that consumes this verb — runs before that. get-module-context is a read-only reader, so it degrades to the checkout root and reports the degradation rather than failing; the shared --plan-id resolver keeps its fatal contract for every write-side caller.

---

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-deliverable	--plan-id --deliverable-number N	Read a single deliverable by number (equivalent to read --deliverable-number)
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