# 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.
