Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/analysis/estimate.md

Skill Test Spec: /estimate

Skill Summary

/estimate [task-description] estimates the effort for one task. It reads the task description from the argument (asking for clarification first if it is too vague to estimate), the project context from CLAUDE.md, and any related GDD in design/gdd/ (Phase 1). It scans the affected code for complexity, integration points and test coverage, and reads production/sprints/ for similar completed tasks and historical velocity (Phase 2). It analyzes code complexity, scope and risk (Phase 3), then prints an estimate (Phase 4): a Complexity Assessment table, an Effort Estimate in days for Optimistic / Expected / Pessimistic scenarios, a recommended budget equal to the Expected figure, a Confidence of High / Medium / Low with its drivers, Risk Factors, Dependencies, a Suggested Breakdown with a total, and Notes and Assumptions — followed by a one-line summary and Verdict: COMPLETE — estimate generated. Estimates are rounded to half days. The skill is read-only and invokes no director gates.

---

Static Assertions (Structural)

Checked against the SKILL.md by /skill-test spec — no fixture needed.

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥2 phase headings
• Contains the Optimistic / Expected / Pessimistic scenarios, the High / Medium / Low confidence levels, and the COMPLETE verdict
• Does NOT require "May I write" language (read-only; states that no files are written)
• 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 task in a documented system with existing patterns

Fixture:

• project.yaml: engine.name: godot, so the code root is src/
• design/gdd/combat.md documents melee hit detection
• src/combat/ holds the melee attack code; similar collision code already exists there
• production/sprints/sprint-003.md through sprint-005.md record completed combat tasks

Input: /estimate Add hitbox detection to melee attacks

Expected behavior:

1. Skill restates the task; the description is specific enough, so no clarification is asked
2. Skill reads design/gdd/combat.md because the task relates to a documented system
3. Skill scans src/combat/ for affected files, integration points and existing tests
4. Skill reads production/sprints/ for similar completed tasks and velocity
5. Output follows the Phase 4 template: Complexity Assessment, Effort Estimate (Optimistic / Expected / Pessimistic, in days), Recommended budget, Confidence, Risk Factors, Dependencies, Suggested Breakdown with a Total, Notes and Assumptions
6. Recommended budget equals the Expected figure; all figures are in half-day increments
7. A brief summary gives the recommended budget, the confidence level and the single biggest risk
8. Output ends with Verdict: COMPLETE — estimate generated.; no files are written

Assertions:

• The combat GDD and the sprint history are read before the estimate is produced
• Effort is given as three day figures (Optimistic, Expected, Pessimistic), not a single number
• Recommended budget equals the Expected figure, not the Optimistic one
• Figures are rounded to half days, not hours
• The closing summary names budget, confidence and the biggest risk
• No files are written

---

Case 2: High Uncertainty — New subsystem, no architecture decided

Fixture:

• project.yaml: engine.name: godot
• src/ holds no source files for an online or matchmaking subsystem
• design/gdd/online.md describes the lobby with open "TBD" requirements, and says the networking approach (transport, host model) is not yet decided

Input: /estimate Implement online lobby matchmaking

Expected behavior:

1. Skill reads design/gdd/online.md and finds the unresolved requirements and the undecided networking approach
2. Code scan finds no existing subsystem; "Existing patterns available" is No
3. Risk Factors table lists the specific unknowns: the networking approach the GDD leaves undecided, new technology, unclear requirements
4. Confidence is Low, with the drivers explained
5. Phase 5 recommends a time-boxed spike via /prototype before committing
6. No files are written

Assertions:

• Confidence is Low when the task has an undecided approach, no existing code and TBD requirements
• The Risk Factors table names the specific unknowns driving the uncertainty
• Output recommends a time-boxed /prototype spike before committing
• No files are written

---

Case 3: No Sprint Velocity Data — Estimate still produced, gap stated

Fixture:

• project.yaml: engine.name: godot; src/core/ holds the inventory code the save touches
• design/gdd/save-load.md documents the save system clearly
• production/sprints/ is empty — no historical sprints

Input: /estimate Implement save and load of player inventory

Expected behavior:

1. Skill reads the task, the GDD and the affected code
2. Skill looks for past sprint data and finds none
3. The estimate is still produced with all three scenarios and a recommended budget
4. Notes and Assumptions (or the Confidence explanation) states that no sprint history was available, so the figures are not calibrated to team velocity
5. No figure is padded silently to cover the missing data — any extra risk is called out explicitly
6. No files are written

Assertions:

• Skill does not error or stop when no sprint history exists
• Estimate is still produced with Optimistic, Expected and Pessimistic figures
• Output states that no sprint history was available for velocity calibration
• Any allowance for the missing data is stated as a risk, not hidden in the figures

---

Case 4: Vague Task — Clarification before estimating

Fixture:

• project.yaml: engine.name: godot
• Project has GDDs and source code under src/; sprint history exists

Input: /estimate make combat feel better

Expected behavior:

1. Skill reads the task description and finds it too vague to estimate meaningfully (no scope, no named change)
2. Skill asks for clarification before proceeding
3. No Complexity Assessment, Effort Estimate or verdict is produced until the task is clarified
4. No files are written

Assertions:

• Skill asks for clarification for a task that names no concrete change
• No estimate figures are produced before the clarification is answered
• Verdict: COMPLETE is not printed for an unclarified task
• No files are written

---

Case 5: Gate Compliance — No gate; estimates are informational

Fixture:

• project.yaml: engine.name: godot, modes.review_mode: full
• Task relates to a documented system with medium complexity; its code is under src/

Input: /estimate Add item pickup with inventory stacking

Expected behavior:

1. Skill reads context, scans code and sprint history; produces the estimate
2. No director gate is invoked in any review mode
3. Estimate is presented as advisory output only
4. Next steps include "run /sprint-plan update to add it to 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 the task argument, project context and any related GDD before estimating
• Reads production/sprints/ for similar tasks and velocity when available
• Produces an effort range (Optimistic / Expected / Pessimistic days), not a single number
• Does not write any files
• No director gates are invoked
• Ends with Phase 5 next steps matched to the result (/prototype for Low confidence, /create-stories for tasks over 10 days, /sprint-plan update to schedule)

---

Coverage Notes

• The skill estimates one task per run; a sprint file with several stories is not a supported input.
• The "task over 10 days → break it into smaller stories via /create-stories" branch is not given its own case.
• The accuracy of the day figures depends on the team and is not tested; the assertions check the range's structure, its sources and its stated drivers.