BOHICA-LABS / BOHICA-LABS/vsdd-factory

enhancement(planning): story-vs-BC AC-count ratio as pre-delivery story-quality signal

Open
#281 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2
Forks
1
Avg merge
6h 43m
Merged PRs (30d)
29

Description

## Summary

Stories regularly declare a complexity estimate (small/medium/large or N points) that doesn't account for the size of the underlying behavioral contract they trace to. When the BC's combined AC+EC count exceeds the story's AC count by more than ~2x, the story is functionally under-sized — the BC is the source of truth and the story will need to satisfy the BC's full surface during delivery.

The convergence loop (adversarial review) catches this eventually, but at high token cost. A "small (3pt)" story whose BC has 12 ACs + 9 ECs (~4x ratio) repeatedly produces 8-10 convergence passes because each fix round addresses one slice of the BC and a fresh pass reveals the next slice. The story is structurally Wave-2-sized work labeled as a 3pt slice.

## Observed pattern

Across three stories I've reviewed:
- Story X1: 5 story ACs, BC had 12 ACs + 9 ECs (4.2x). Result: 9 convergence passes.
- Story X2: 6 story ACs, BC had 31 items (5.2x). Predicted heavy convergence; not yet attempted.
- Story X3: 4 story ACs, BC had 27 items (6.75x). Predicted heavy; not yet attempted.

The drift is invisible at planning time because the story-quality gates check story-internal consistency (frontmatter, AC numbering, trace links) but don't compare the story body to the BC body.

## Suggested mitigation

Add a pre-delivery story-quality check (skill or hook):

```
For each story:
read story_ac_count from the story file
read bc_item_count from the linked BC file (AC count + EC count)
ratio = bc_item_count / story_ac_count
if ratio > 2.0:
warn: story complexity may be under-sized vs BC scope
recommend: split story OR rescope BC OR escalate to story-writer
```

This can run as part of the existing `/vsdd-factory:check-implementation-readiness` skill (cross-cutting), or as a new `/vsdd-factory:check-story-bc-ratio` skill.

## Related

- #267 (state-manager source-of-truth validation) — sibling about cross-document consistency checks
- #261 (privacy meta) — for context, this is filed in the abstract to avoid leaking project specifics

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.