OBS-08: Methodology-neutrality principle for decomposition agents

[b-coman]

Origin

E2E Round 3, OBS-08 — Design Gap, Low/Medium severity (see reports/e2e-003-ido4shape-cloud.md lines 352–405).

Surfaced during Phase 2 output review: Claude's Stage 1 summary used the phrase "consider serializing in wave planning" to describe scheduling three high-risk capabilities. "Wave" is Hydro-specific terminology, but the pipeline is methodology-agnostic until Phase 3 Stage 2 (ingestion).

Problem

Decomposition is methodology-agnostic by design. The round-1 design finding explicitly says: "Methodology enters at ingestion (Stage 3b/4), not before — project initialization before dry-run." The initialization check sits at skills/decompose-validate/SKILL.md:65-77 (Phase 3 Stage 2, after structural review, before dry-run), which matches the intent.

But Claude's synthesis in Phase 1 and Phase 2 can leak methodology-specific terminology into:

• Chat summaries (confirmed: "consider serializing in wave planning")
• Written artifacts (not yet confirmed — canvas and tech spec on disk have zero strict matches for wave|waves|sprint|cycle|bet)

Why this matters

• Pre-commits the user to a specific methodology before they've explicitly chosen one
• Biases the refine skill's suggestions — if user edits assuming wave-based planning, the spec bakes it in
• Undermines the "methodology-agnostic until ingestion" design intent from round 1
• Low-Medium severity NOW because written artifacts are clean. Would escalate to Medium if the summary habit migrates into written output — plausible once the refine skill (OBS-06: Build unified decompose-refine skill (canvas mode + technical-spec mode) #5) is editing descriptions

Verification of current state (2026-04-11)

• Canvas on disk: zero strict matches for wave|waves|sprint|cycle|bet ✓
• Technical spec on disk: zero strict matches ✓
• Chat-level Stage 1 summary: ONE leak — "consider serializing in wave planning"
• Initialization check location: correct — decompose-validate Stage 2, unchanged ✓

Fix approach — principle + example

Consistent with OBS-07's (#3) reframing and OBS-09's (#2) meta-concern about rule accumulation.

For agents/technical-spec-writer.md AND agents/code-analyzer.md — 1 shared principle

Methodology neutrality. Decomposition is methodology-agnostic. Methodology enters at ingestion (Phase 3 Stage 2), not before. Task descriptions, capability descriptions, summaries, and any chat output in Phases 1 or 2 use neutral terminology. If the strategic spec itself uses methodology-specific terminology, quote it verbatim (context preservation) but do not adopt the terminology in your own prose.

Example block

LEAK:
  Consider serializing STOR-05, PLUG-02, and VIEW-05 in wave
  planning despite the graph allowing parallelism — stress
  testing bandwidth is limited.

NEUTRAL:
  Consider executing STOR-05, PLUG-02, and VIEW-05 sequentially
  rather than in parallel when scheduling — stress testing
  bandwidth is limited.

WHAT MOVED: "wave planning" implied Hydro. "When scheduling" is
methodology-agnostic — still captures the constraint without
presupposing a container type.

Skill-level reminders (one line each)

skills/decompose/SKILL.md (Stage 1 summary) and skills/decompose-tasks/SKILL.md (Stage 1c summary):

"The summary must be methodology-neutral. Methodology enters at ingestion (Phase 3 Stage 2)."

No changes needed

• skills/decompose-validate/SKILL.md — initialization check is correctly placed at Stage 2. The round-1 design finding is upheld.

Deliverables

• agents/technical-spec-writer.md — 1 new principle (methodology neutrality)
• agents/code-analyzer.md — same principle (shared text)
• 1 example block demonstrating leak → neutral pattern (in one or both agents)
• skills/decompose/SKILL.md — one-line reminder in Stage 1 summary instructions
• skills/decompose-tasks/SKILL.md — one-line reminder in summary instructions
• Principles land INTO the audited rule set (after OBS-09: Rule audit across agents and decompose skills #2 completes)

Acceptance criteria

• Principle is concise (2-3 sentences, not a forbidden-term list)
• No enumeration of methodology-specific terms as a blocklist
• Example block shows LEAK → NEUTRAL → WHAT MOVED pattern
• One-line skill reminders are exactly one line, not a sub-section
• decompose-validate/SKILL.md is NOT modified (initialization check stays as-is)
• Consistent with prompt strategy doc (Prompt strategy doc — cross-suite governance for skill/agent/prompt authoring #1) principles

Calibration

Round 5: re-run decomposition on same strategic spec, grep chat-output summaries for methodology terms (wave|waves|sprint|cycle|bet|pitch|backlog|standup|retro). Zero matches in written artifacts = fix landed.

Dependencies

• Blocked by: OBS-09: Rule audit across agents and decompose skills #2 (OBS-09 rule audit)
• Blocks: OBS-06: Build unified decompose-refine skill (canvas mode + technical-spec mode) #5 (OBS-06 decompose-refine skill)

References

• reports/e2e-003-ido4shape-cloud.md — OBS-08 (lines 352–405)
• skills/decompose-validate/SKILL.md — initialization check (lines 65–77)
• Three methodology profiles: Hydro (waves), Scrum (sprints), Shape Up (cycles+bets) — defined in @ido4/core/profiles/