Orchestrata Ultimate › Plans › spec-consolidation-analysis

Spec consolidation — diagnosis + plan (2026-08-02)

Source: plans/spec-consolidation-analysis.md at 8a2cb42ad · last changed 2026-08-10 · first committed 2026-08-02 · 70 lines.

Prose pending.

Plan text

Spec consolidation — diagnosis + plan (2026-08-02)

User thesis: the specs are "disjointed features with no use-case usage-scenario narrative." Confirmed, quantitatively, via trace_intel/code_intel + a structural scan (deterministic-first — no spec read by hand to get these).

Diagnosis (evidence)

1. Systemic template defect — the root of "disjointed features"

• 65 of 67 spec.md files carry Functional Requirements (flat FR-NNN lists).
• Only 6 carry any Use-Case / Actor / Scenario / User-Story narrative: 031-qa-volk, 028-llm-client, 068-schedule-cron-tool, 098-api-standards, 102-volk-test-harness, 070-team-tools.
• The other 59 go Overview → Terminology → Data Models → Functional Requirements with no section binding FRs to who-does-what-and-why.
• The 6 good specs share one extra section the 59 lack: ## User Stories (spec-102 shape: Overview(What/Why/How) → User Stories → Terminology → Functional Requirements → Error Conditions). That is the missing narrative.

2. Traceability is a one-directional CONNECTION gap, not vaporware

Distinct requirement ids (code @traces vs spec definitions):

• 1822 connected (code cites AND a spec defines) — the vocabularies mostly agree.
• 24 dangling (code cites, no spec defines) — all in the ad-hoc REQ-001-9xx defect-regression range; trivial to reconcile.
• 1604 untraced (spec defines, no code cites) = 2419 entries across 44 specs.
• The untraced set is concentrated: the top 5 specs are 53% of it — 021(282), 007(277), 016(256), 002(236), 020(232) — and all five are backed by 20–61 module packages (session 61, gateway 38, postman 30, governance 27, harness 20). The features EXIST; the FRs are just not narrated or @traced. This is connectable, not a rebuild.

3. One structural collision

007 is used twice: 007-prolog-governance AND 035-verification → every REQ-007-* id is ambiguous between two specs.

Plan — organize + connect, do NOT rebuild

A. Canonical spec template (the organizational fix)

Adopt the spec-102 structure as canonical: every spec gains a ## User Stories section (Actor → Goal → Scenario) that each FR-NNN maps to. Retrofit the 59 flat specs to it, highest-untraced first. Gives every FR a usage narrative and makes "what is this feature for / who triggers it" answerable — the core fix.

B. Traceability reconciliation (deterministic, tool-driven)

Per untraced spec req in a code-backed spec: use trace_intel + code_intel (callers/impact/find-symbol) to locate the implementing symbol(s) and add @traces (implemented → connect); FRs with no implementing code become an explicit backlog/gap, never silently untraced. The 24 dangling REQ-001-9xx: define in the owning spec or remove. Drives the 2419 down with evidence, not guesswork.

C. Fix the 007 collision

Renumber 035-verification to the next free spec number; remap its REQ-007-* range; update the @traces that cite it.

D. Prioritization

021, 007, 016, 002, 020 first (53% of untraced, all code-backed → highest ROI). Each spec: (1) add the User-Stories narrative, (2) triage its untraced FRs (connect vs backlog).

Execution model (division of labor)

• Opus (design/organization, my lane): the canonical template, the per-spec User-Stories structure, the triage rules (connect vs backlog), collision remap.
• Builders (mechanical retrofit to a settled brief): per-spec — insert the narrative section, add @traces where code_intel locates the implementation, file backlog items for genuine gaps. Gated by check-traces/trace-lint.

Verification loop

trace_intel report before/after each spec: untraced_reqs must fall by the connected count; specless_usecases must fall as narratives land. The number is the scoreboard.

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks