OBS-06: Build unified decompose-refine skill (canvas mode + technical-spec mode)

[b-coman]

Origin

E2E Round 3, OBS-06 — Design Gap, Medium severity (see reports/e2e-003-ido4shape-cloud.md lines 176–229).

Surfaced during Phase 1 completion, broadened after Phase 2 completion. The same gap exists between BOTH Phase 1→Phase 2 AND Phase 2→Phase 3: the user is handed an artifact and asked to "review then proceed" without any supported way to actually refine the artifact.

Problem

Phase 1 ends with "Review the canvas, then run /ido4dev:decompose-tasks". Phase 2 ends with "Review the technical spec, then run /ido4dev:decompose-validate". Both are passive reviews — the user can read and decide whether to proceed, but has no supported way to add, correct, or extend the artifact.

Knowledge the user has that the automated synthesis missed gets lost, injected at the wrong stage, or forced in via manual editing without guardrails (risking downstream breakage — canvas edits might break spec-writer's consumption, tech spec edits might break parser compliance or the dependency graph).

Concrete gray areas (from Phase 2 output)

• 3 high-risk capabilities parallelize per the dep graph but Phase 2 flagged a chaos-testing bandwidth concern recommending serialization — a scheduling decision the user should confirm
• 6+ research spikes guarding blocking decisions — the user may already know the answer to some
• Effort/risk metadata across 94 tasks — the user may have strong priors that differ
• Task bundling choices (Goldilocks is a heuristic) — user may want to split or merge
• Stakeholder attribution gaps — user may want to add omitted attributions
• Captured design decisions — user may want to override

Why this matters

The pipeline is AI-hybrid development governance. The human-in-the-loop value lives at between-phase checkpoints. A passive "proceed or not" gate doesn't capture the user's technical knowledge — it only gates its propagation. Mistakes in the technical spec are especially costly because the spec becomes GitHub issues at ingestion — post-ingestion corrections require editing issues directly.

Design — unified skill with mode detection

/ido4dev:decompose                — Phase 1: canvas
/ido4dev:decompose-refine    NEW  — Phase 1.5 OR 2.5: refine canvas or tech spec
/ido4dev:decompose-tasks          — Phase 2: technical spec from canvas
/ido4dev:decompose-validate       — Phase 3: validate + ingest

Mode detection

Input: $ARGUMENTS is a path to either a canvas or a technical spec. Skill detects artifact type from structure:

• # Technical Canvas: header → canvas mode → reads agents/code-analyzer.md for template + rules
• # ... — Technical Spec header → technical-spec mode → reads agents/technical-spec-writer.md for template + rules

Conversational loop (same in both modes)

Read artifact + template → open with short summary + prompt → per user turn either:

1. Answer question about the artifact
2. Propose edit in diff form
3. Flag cross-section contradiction
   → Apply on approval → validate post-edit → exit on "done" or direct forward invocation

Mode-specific guardrails

Aspect	Canvas mode	Technical-spec mode
Preserve verbatim	Strategic context (descriptions, success conditions, stakeholder attributions, group context)	Capability descriptions (carry canvas + strategic context forward), parser format compliance
Forbidden edits	Add/remove ## Capability: sections, reorder capabilities	Add/remove ## Capability: sections, break parser format, break dependency graph
Allowed edits	Complexity Assessment, Discoveries & Adjustments, Code-Level Dependencies, Cross-Cutting Concern notes	Task descriptions, metadata values, success conditions, dependencies. Add/remove/split/merge tasks within a capability
Post-edit validation	Template section presence	Parser compliance check (ref format, metadata keys, allowed values), dependency graph still validates

Why one unified skill beats two separate ones

1. Same conversational loop — read, ask, propose, approve, apply, validate, exit
2. One skill to learn — user doesn't need to remember which refine skill for which artifact
3. DRY — conversational pattern, approval flow, and diff-apply-validate cycle are shared
4. Easier to extend — future artifact types add a mode, not a sibling skill
5. Precedent in the plugin: sandbox handles create/reset/destroy as modes of one skill

Connection to OBS-07 (intent-over-prescription)

In technical-spec mode, the refine skill reads agents/technical-spec-writer.md — which now contains the intent-over-prescription principle (#3) and the Good vs Bad example. Claude applies the same principle to the refinement loop. When the user asks to refine a task, Claude can notice over-prescription and propose a rewrite. No separate detection-pattern list needed.

Deliverables

• skills/decompose-refine/SKILL.md — new (~160 lines covering both modes)
• commands/decompose-refine.md — new command shim
• skills/decompose/SKILL.md — update end-of-Phase-1 guidance to mention refinement as optional next step
• skills/decompose-tasks/SKILL.md — update end-of-Phase-2 guidance to mention refinement as optional next step
• README.md + CLAUDE.md — skill count bump 23 → 24
• Include TodoWrite task-list instruction for consistency (per OBS-10 fix pattern from Round 3)

Acceptance criteria

• Mode detection correctly identifies canvas vs technical spec from headers
• Canvas mode forbids adding/removing capability sections
• Technical-spec mode runs parser compliance check after every edit
• Conversational loop exits cleanly on "done" or forward invocation
• End-of-phase guidance in decompose and decompose-tasks mentions refinement as optional
• Skill follows prompt strategy doc (Prompt strategy doc — cross-suite governance for skill/agent/prompt authoring #1) principles (no rule accumulation in the new skill)

Pre-requisites

None at the infrastructure level. No changes to agents, MCP server, Phase 2, or Phase 3 skills (beyond updating end-of-phase guidance). Purely additive.

Dependencies

• Blocked by: OBS-07: Intent-over-prescription principle for agent definitions #3 (OBS-07) and OBS-08: Methodology-neutrality principle for decomposition agents #4 (OBS-08) — the refine skill reads agent files that contain these principles
• Blocked by: OBS-09: Rule audit across agents and decompose skills #2 (OBS-09) — agent definitions should be stable before the refine skill references them

References

• reports/e2e-003-ido4shape-cloud.md — OBS-06 (lines 176–229)
• skills/sandbox/SKILL.md — precedent for multi-mode skill pattern
• agents/code-analyzer.md — read by canvas mode for template + rules
• agents/technical-spec-writer.md — read by tech-spec mode for template + rules
• Round 3 technical spec: ido4shape-cloud/specs/ido4shape-enterprise-cloud-technical.md (1317 lines, 94 tasks, 29 capabilities)

[b-coman]

Update from architecture research (2026-04-12)

Two findings from the prompt strategy investigation relevant to this skill's design:

1. Monolithic skill is the correct architecture here

The prompt strategy doc's "when to split" decision table confirms decompose-refine should be a single skill, not split per mode. The reasoning:

• It's a conversational loop with no human checkpoint needed within the loop
• The user stays engaged throughout (propose → approve → validate → repeat)
• Anthropic's own reference implementation (doc-coauthoring) uses a single skill for a similar multi-stage conversational pattern

This validates the original design in the OBS-06 report.

2. Consider a skill-scoped PostToolUse hook for technical-spec mode

Skills can define hooks in their frontmatter, scoped to fire only during that skill's execution. In technical-spec mode, a skill-scoped PostToolUse hook on Write/Edit could run a lightweight parser compliance check (ingest_spec dry-run) after every edit. This catches format drift incrementally during the refinement loop rather than only when the user exits and runs decompose-validate.

This is an optional enhancement, not a blocker. The skill works without it — but it's worth evaluating during implementation.

Source: Claude Code Hooks docs — skill-scoped hooks. Architecture rationale in ~/dev-projects/ido4-suite/docs/prompt-strategy.md under "Skill architecture patterns."