169 lines
6.0 KiB
Markdown
169 lines
6.0 KiB
Markdown
# Skill Test Spec: /estimate
|
||
|
||
## Skill Summary
|
||
|
||
`/estimate` estimates task or story effort using a relative-size scale (S / M /
|
||
L / XL) based on story complexity, acceptance criteria count, and historical
|
||
sprint velocity from past sprint files. Estimates are advisory and are never
|
||
written automatically. No director gates are invoked. Verdicts are effort ranges,
|
||
not pass/fail — every run produces an estimate.
|
||
|
||
---
|
||
|
||
## Static Assertions (Structural)
|
||
|
||
Verified automatically by `/skill-test static` — no fixture needed.
|
||
|
||
- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
|
||
- [ ] Has ≥2 phase headings
|
||
- [ ] Contains size labels: S, M, L, XL (the "verdict" equivalents for this skill)
|
||
- [ ] Does NOT require "May I write" language (advisory output only)
|
||
- [ ] Has a next-step handoff (how to use the estimate in sprint planning)
|
||
|
||
---
|
||
|
||
## Director Gate Checks
|
||
|
||
None. Estimation is an advisory informational skill; no gates are invoked.
|
||
|
||
---
|
||
|
||
## Test Cases
|
||
|
||
### Case 1: Happy Path — Clear story with known tech stack
|
||
|
||
**Fixture:**
|
||
- `production/epics/combat/story-hitbox-detection.md` exists with:
|
||
- 4 clear Acceptance Criteria
|
||
- ADR reference (Accepted status)
|
||
- No "unknown" or "TBD" language in story body
|
||
- `production/sprints/sprint-003.md` through `sprint-005.md` exist with velocity data
|
||
- Tech stack is GDScript (well-understood by team per sprint history)
|
||
|
||
**Input:** `/estimate production/epics/combat/story-hitbox-detection.md`
|
||
|
||
**Expected behavior:**
|
||
1. Skill reads the story file — assesses clarity, AC count, tech stack
|
||
2. Skill reads sprint history to determine average velocity
|
||
3. Skill outputs estimate: M (1–2 days) with reasoning
|
||
4. No files are written
|
||
|
||
**Assertions:**
|
||
- [ ] Estimate is M for a clear, well-scoped story with known tech
|
||
- [ ] Reasoning references AC count, tech stack familiarity, and velocity data
|
||
- [ ] Estimate is presented as a range (e.g., "1–2 days"), not a single point
|
||
- [ ] No files are written
|
||
|
||
---
|
||
|
||
### Case 2: High Uncertainty — Unknown system, no ADR yet
|
||
|
||
**Fixture:**
|
||
- `production/epics/online/story-lobby-matchmaking.md` exists with:
|
||
- 2 vague Acceptance Criteria (using "should" and "TBD")
|
||
- No ADR reference — matchmaking architecture not yet decided
|
||
- References new subsystem ("online/matchmaking") with no existing source files
|
||
|
||
**Input:** `/estimate production/epics/online/story-lobby-matchmaking.md`
|
||
|
||
**Expected behavior:**
|
||
1. Skill reads story — finds vague AC, no ADR, no existing source
|
||
2. Skill flags multiple uncertainty factors
|
||
3. Estimate is L–XL with an explicit risk note: "Estimate range is wide due to architectural unknowns"
|
||
4. Skill recommends creating an ADR before development begins
|
||
|
||
**Assertions:**
|
||
- [ ] Estimate is L or XL (not S or M) when significant unknowns exist
|
||
- [ ] Risk note explains the specific unknowns driving the wide range
|
||
- [ ] Output recommends resolving architectural questions first
|
||
- [ ] No files are written
|
||
|
||
---
|
||
|
||
### Case 3: No Sprint Velocity Data — Conservative defaults used
|
||
|
||
**Fixture:**
|
||
- Story file exists and is well-defined
|
||
- `production/sprints/` is empty — no historical sprints
|
||
|
||
**Input:** `/estimate production/epics/core/story-save-load.md`
|
||
|
||
**Expected behavior:**
|
||
1. Skill reads story — assesses complexity
|
||
2. Skill attempts to read sprint velocity data — finds none
|
||
3. Skill notes: "No sprint history found — using conservative defaults for velocity"
|
||
4. Estimate is produced using default assumptions (e.g., 1 story point = 1 day)
|
||
5. No files are written
|
||
|
||
**Assertions:**
|
||
- [ ] Skill does not error when no sprint history exists
|
||
- [ ] Output explicitly notes that conservative defaults are being used
|
||
- [ ] Estimate is still produced (not blocked by missing velocity)
|
||
- [ ] Conservative defaults produce a higher (not lower) estimate range
|
||
|
||
---
|
||
|
||
### Case 4: Multiple Stories — Each estimated individually plus sprint total
|
||
|
||
**Fixture:**
|
||
- User provides a sprint file: `production/sprints/sprint-007.md` with 4 stories
|
||
- Sprint history exists (3 previous sprints)
|
||
|
||
**Input:** `/estimate production/sprints/sprint-007.md`
|
||
|
||
**Expected behavior:**
|
||
1. Skill reads sprint file — identifies 4 stories
|
||
2. Skill estimates each story individually: S, M, M, L
|
||
3. Skill computes sprint total: approximately 6–8 story points
|
||
4. Skill presents per-story estimates followed by sprint total
|
||
5. No files are written
|
||
|
||
**Assertions:**
|
||
- [ ] Each story receives its own estimate label
|
||
- [ ] Sprint total is presented after individual estimates
|
||
- [ ] Total is a sum range derived from individual ranges
|
||
- [ ] Skill handles sprint files (not just single story files) as input
|
||
|
||
---
|
||
|
||
### Case 5: Gate Compliance — No gate; estimates are informational
|
||
|
||
**Fixture:**
|
||
- Story file exists with medium complexity
|
||
- `review-mode.txt` contains `full`
|
||
|
||
**Input:** `/estimate production/epics/core/story-item-pickup.md`
|
||
|
||
**Expected behavior:**
|
||
1. Skill reads story and sprint history; computes estimate
|
||
2. No director gate is invoked in any review mode
|
||
3. Estimate is presented as advisory output only
|
||
4. Skill notes: "Use this estimate in /sprint-plan when selecting stories for the next sprint"
|
||
|
||
**Assertions:**
|
||
- [ ] No director gate is invoked regardless of review mode
|
||
- [ ] Output is purely informational — no approval or write prompt
|
||
- [ ] Next-step recommendation references `/sprint-plan`
|
||
- [ ] Estimate does not change based on review mode
|
||
|
||
---
|
||
|
||
## Protocol Compliance
|
||
|
||
- [ ] Reads story file before estimating
|
||
- [ ] Reads sprint velocity history when available
|
||
- [ ] Produces effort range (S/M/L/XL), not a single number
|
||
- [ ] Does not write any files
|
||
- [ ] No director gates are invoked
|
||
- [ ] Always produces an estimate (never blocked by missing data; uses defaults instead)
|
||
|
||
---
|
||
|
||
## Coverage Notes
|
||
|
||
- The skill does not produce PASS/FAIL verdicts; the "verdict" here is the
|
||
effort range itself. Test assertions focus on the accuracy of the range
|
||
and the quality of the reasoning, not a binary outcome.
|
||
- Team-specific velocity calibration (what "M" means for this team) is an
|
||
implementation detail not tested here; it is configured via sprint history.
|