Feature: Per-Story Uncertainty Removal + Self-Containment Review (Pre-Phase-3 Quality Gate)

# Feature Request: Per-Story Uncertainty Removal + Self-Containment Review (Pre-Phase-3 Quality Gate)

## Summary

Add a new skill `/vsdd-factory:story-uncertainty-review` that runs a structured per-story completeness audit between Phase 2 (Story Decomposition) and Phase 3 (TDD Implementation) dispatch. The skill adapts the existing `/dclaude:remove-uncertainty` pattern, extending it from "tech-uncertainty only" to "tech-uncertainty + LLM cold-context self-containment" across 5 dimensions.

## Problem Statement

By the time Phase 2 closes, the story corpus has converged adversarially — all internal contradictions resolved, BC/VP/edge-case traceability complete, dependency graph clean. However, **convergence is not the same as fresh-context executability**. A story can be perfectly internally consistent and still be unexecutable by a fresh-context LLM with no prior project knowledge, for reasons including:

1. **Stale tech claims** — version pin claims that lag behind the dependency manifest's actual canonical values
2. **Vague references** — citations like "see BC-X §Y" without an anchor that an LLM grepping cold can resolve
3. **Spec divergence** — story's inlined supporting-type definitions (enum variants, struct fields) drift from the canonical SS-*.md source
4. **Implementation gaps** — file paths, function signatures, test fixture content, library pins required for the impl but not enumerated in the story
5. **Cross-story handoff opacity** — `depends_on` lists predecessor stories but doesn't summarize WHAT outputs (paths, symbols, types) they produce

Each of these defects costs hours-to-days during Phase 3 implementation as the implementer agent either:
- Infers incorrectly and ships divergent code (caught later by adversary or formal verifier — expensive)
- Stops to chase 5+ spec files (context overflow risk; reasoning quality decay)
- Surfaces the question to the orchestrator (fine, but interrupts flow)

These costs are largely avoidable: a fresh-context spec-reviewer pass per story catches them BEFORE Phase 3 dispatch.

## Proposed Skill

`/vsdd-factory:story-uncertainty-review`

**Workflow position:** Phase 2 GATE PASS (or GATE PASS WITH RESIDUAL) → **NEW story-uncertainty-review skill** → Phase 3 dispatch.

**Input:** All story files in `.factory/stories/` matching the project's story-id pattern.

**Output:**
- Per-story assessment report (under `.factory/plans/story-uncertainty-review//`)
- Master uncertainty inventory aggregating findings across all stories
- Research queue (Perplexity/Context7 validations needed)
- Remediation dispatch plan (per-finding routing to story-writer / architect / product-owner / research-agent)

## Five-Dimension Assessment Framework

| Dim | What it covers | Typical defect |
|-----|----------------|---------------|
| **A. Tech Uncertainty** | Crate version pinning consistency vs canonical dependency manifest; current API/method names; deprecated patterns; unpinned versions | Story uses `tokio = "=1.52"` while manifest uses canonical triplet `tokio = "=1.52.0"`; `prost` missing from EXACT-pin list despite manifest mandate |
| **B. Context Gap** | Vague references without anchors; missing version pins on referenced files; BC postcondition / VP probe / edge case / supplement clauses cited without specificity | Story cites "BC-2.01.003 §Body Size Limit" without line anchor; cold LLM has to scan whole file |
| **C. AC Executability** | Acceptance criteria measurability; pass/fail boundary explicitness; trace to specific BC postcondition / VP probe / edge case; oracle definition | AC says "proceeds to the handler" — what HTTP status counts as "proceeds"? |
| **D. Implementation Detail** | Concrete file paths; function signatures, struct fields, error variants either inline or anchored; complete library/file structure requirements | Story names file `router.rs` but VP says `server.rs`; supporting-type enum has 3 variants inline while canonical spec has 5 |
| **E. Cross-Story Dependency** | `depends_on` summary of WHAT predecessors provide; "Previous Story Intelligence" coverage; downstream consumer surface for `blocks` | `depends_on: [S-001]` says only "axum 0.8.9 pinned" — doesn't enumerate workspace crates S-001 establishes that this story imports |

## Four-Stage Workflow

```
Stage 1 — SCAN (parallel per story)
├─ Dispatch: vsdd-factory:spec-reviewer per story (fresh context, different model family)
└─ Output: Structured 5-dimension report per story
(verdict: PASS | PASS_WITH_OBSERVATIONS | NEEDS_REVISION | NEEDS_RESEARCH)

Stage 2 — RESEARCH (parallel per question)
├─ Dispatch: vsdd-factory:research-agent per Q in research queue
└─ Output: Per-question confirmation/refutation with Perplexity/Context7 citations

Stage 3 — FIX (serialized per story; parallel across independent stories)
├─ Dispatch: vsdd-factory:story-writer (per story) — may cross-route to:
│ ├─ vsdd-factory:architect (if spec drift / pin manifest update)
│ ├─ vsdd-factory:product-owner (if BC/PRD edit needed)
│ └─ vsdd-factory:consistency-validator (after fix, before verify)
└─ Output: Fixed story file + version bump + §Trace entry + input-hash recompute

Stage 4 — VERIFY (parallel per story)
├─ Dispatch: vsdd-factory:spec-reviewer (fresh context) per fixed story
└─ Output: Verdict per story must be PASS or PASS_WITH_OBSERVATIONS to clear Phase 3 dispatch
(loops back to Stage 3 with new findings if NEEDS_REVISION)
```

## Evidence — Calibration on monocle (2026-05-19/20)

We ran the framework against 3 calibration stories in the **monocle** project (greenfield-with-reference-ingest, Phase 2 GATE PASS WITH RESIDUAL finalized, 17-story corpus). Stories were selected to span complexity range: smallest (S-004, 116 lines), mid (S-014, 173 lines), largest (S-001, 182 lines).

| Story | Complexity | Verdict | CRIT findings | Notable defect |
|---|---|---|---|---|
| **S-001** (Cargo workspace + CI) | largest | NEEDS_REVISION | 2 CRIT + 4 HIGH | `prost` missing from EXACT-pin list despite manifest mandate; `bytes 1.10` not declared (would have shipped with active RUSTSEC-2026-0007 exposure); CI matrix cross-product produces nonsensical runner/target combos (`macos × linux-gnu`) |
| **S-004** (body size limit) | smallest | NEEDS_REVISION | 1 CRIT + 1 HIGH | AC-005 contradicts BC-2.01.003 PC-3 + VP-003 PC-4 about `/status` router membership; uses wrong edge-case ID (EC-002 vs canonical EC-045) — cold LLM grepping for EC-002 in BC-2.01.003 finds nothing |
| **S-014** (EngineModule trait) | mid | NEEDS_REVISION | 3 CRIT | Inlined `SessionStatus` has 3 variants `{Running, Idle, Exited}` vs spec's 5 `{Active, Idle, WaitingOnPermission, Stopping, Stopped}`; `HookResponse` field set diverges from spec (omits `redirect_url`/`diagnostic`, fabricates `deferred_until`); ghost `DeferUntil` type referenced with no canonical definition |

**Hit rate on calibration: 3/3 stories needed revision. ≥1 CRIT-class defect in every story.** Each of these defects would have shipped divergent code in Phase 3, costing implementation hours plus adversary cycles plus formal-verifier cycles to detect downstream.

Calibration cost: ~60-90 seconds per spec-reviewer dispatch × 3 = ~5 minutes wall time. Estimated savings per defect caught: 2-4 hours of Phase 3 + Phase 5 adversary cycles. ROI clearly positive even at this small sample.

## Integration Points

1. **New skill file:** `skills/story-uncertainty-review/SKILL.md`
2. **Agent prompt template:** Embedded in skill; primary agent is `vsdd-factory:spec-reviewer` (cognitive diversity, different model family from the story-writer that produced the corpus)
3. **Workflow position:** Insert between Phase 2 GATE PASS and Phase 3 dispatch in:
- `workflows/greenfield.lobster`
- `workflows/brownfield.lobster`
- `workflows/feature.lobster` (per-feature story set)
4. **Artifact path registry update:** `.factory/plans/story-uncertainty-review//` (per-story reports) + `.factory/plans/story-uncertainty-review//master-inventory.md`
5. **STATE.md phase tag:** New tag `phase-2.5-story-uncertainty-review` between Phase 2 GATE PASS and Phase 3 ready
6. **Mandatory step in orchestrator (`agents/orchestrator/AGENTS.md`):** Add to MANDATORY STEPS list: "Pre-Phase 3: story-uncertainty-review — always runs against full story corpus; produces master uncertainty inventory; CRIT-finding count must be 0 to clear Phase 3 dispatch (HIGH/MED/LOW are project-configurable thresholds)"

## Relation to Existing Skills

- **`/dclaude:remove-uncertainty`**: This is the seed skill. dclaude's variant focuses narrowly on tech-uncertainty research via Perplexity. This proposal extends to 4 additional dimensions (context, AC, impl, cross-story) and formalizes the scan/research/fix/verify lifecycle.
- **`/vsdd-factory:validate-consistency`**: Cross-document consistency is different from per-story self-containment. validate-consistency finds *broken* links and ID mismatches; story-uncertainty-review finds *vague but technically-valid* links that a cold LLM cannot resolve efficiently.
- **`/vsdd-factory:adversarial-review`**: Adversarial review finds defects WITHIN a converged perimeter. story-uncertainty-review checks whether the perimeter IS the right perimeter for fresh-context execution.
- **`/vsdd-factory:spec-drift`**: spec-drift compares implementation against spec. story-uncertainty-review compares story against spec BEFORE implementation begins.

## Open Design Questions

1. **Stage 4 threshold:** Should the verification gate require zero CRIT findings, zero findings of any severity, or be project-configurable via `.factory/policies.yaml`?
2. **Auto-routing vs report-only:** Should the skill produce an auto-routing dispatch plan, or only the report (orchestrator routes manually)? Auto-routing is faster but risks racing version bumps across parallel story-writer bursts (the SE-18 worktree-race pattern observed in monocle Phase 1).
3. **Self-containment threshold:** What's the right metric for "story is self-contained enough"? Body-token-count proxy (story ≥ 800 tokens of body content)? Findings-per-story (≤ 2 LOW remaining)? Story-level "cold-LLM executability score"?
4. **Scope:** Should the skill cover non-story artifacts (epics, dependency-graph, holdout-scenarios, wave-schedule)? Or stay tightly per-story?
5. **Cost guardrails:** For projects with large story corpora (50+ stories), should the skill support sampling (e.g., scan N random stories per wave) or always run full?

## Proposed Acceptance Criteria for the Capability Itself

- **AC-1:** Skill produces structured 5-dimension report per story with FINDING-IDs, severity labels (CRIT/HIGH/MED/LOW), and research-required flag.
- **AC-2:** Master inventory aggregates findings across all stories with routing recommendations per finding.
- **AC-3:** Research-agent integration validates flagged tech uncertainties via MCP (Perplexity / Context7).
- **AC-4:** Stage 4 verification confirms PASS/PASS_WITH_OBSERVATIONS verdict per story before Phase 3 dispatch clears.
- **AC-5:** Per-story reports are committed under `.factory/plans/` in the cycle directory structure.
- **AC-6:** STATE.md phase transition recorded by state-manager.
- **AC-7:** Skill is idempotent — re-running after no story changes produces same findings (deterministic).
- **AC-8:** Skill produces a Phase-3-dispatch-readiness summary (counts by severity, pass rate, remaining-CRIT list) for human review at the gate.

## Project Provenance

This capability was field-developed on the **monocle** project (single-binary Rust TUI for AI coding harness sessions; 5-plane architecture; 17-story Phase 1 corpus across 4 waves) during the Phase 2 → Phase 3 transition (2026-05-19/20). The calibration described above ran against 3 representative stories and is being expanded to the full 17-story corpus in monocle's `.factory/plans/story-uncertainty-review/` (in-progress as of this issue filing).

Reach out to the monocle project for the full calibration report once the 17-story run completes — it will provide a complete real-world worked example to model the upstream skill on.

---

**Suggested label:** `enhancement` `phase-3-readiness` `quality-gate` `skill-proposal`