pradeepmouli/speckit-superb-review

Task Coverage Review — After Task Generation

Invocation: Optional post-hook for speckit.tasks. Fires after tasks.md is generated. Purpose: Prevent "all tasks done, feature incomplete" — the most expensive form of rework.

---

Why This Matters

tasks.md is generated from plan.md and spec.md, but it is a mechanical transformation. Requirements can fall through the cracks when:

• A user story has implied behaviors that were not written down
• Edge cases in spec.md were noted but not translated into tasks
• A data-model constraint was discussed in research.md but never became a task
• Task granularity is uneven — one task does too much and hides incomplete coverage

This review catches all of these before a single line of code is written.

---

User Context

$ARGUMENTS

Process — Execute in Order

Step 1 — Load Artifacts

Read the following files (all from the current feature directory):

1. spec.md — the authoritative source of requirements
2. plan.md — the technical approach and architecture decisions
3. tasks.md — the generated implementation plan
4. data-model.md (if exists) — entity and relationship constraints
5. contracts/ (if exists) — interface contracts

If spec.md is missing, STOP and report:

ERROR: spec.md not found. Cannot perform coverage review without the spec.
Run speckit.specify first.

---

Step 2 — Extract Requirements from spec.md

Produce a numbered list of every distinct, testable requirement from spec.md:

Format:

R01: [requirement — one sentence, action-oriented]
R02: [requirement]
...

Include:

• Every user story acceptance criterion
• Every constraint mentioned ("must not", "shall not", "required")
• Every non-functional requirement (performance, security, compatibility)
• Every error/edge case described

Mark each requirement as:

• [TESTABLE] — can be verified by a test
• [OBSERVABLE] — can be verified by running the feature
• [STRUCTURAL] — architectural constraint (no direct test, but verifiable via code review)

---

Step 3 — Map Requirements to Tasks

For each requirement R-XX, find which task(s) in tasks.md implement it.

Produce the coverage matrix:

| Req  | Requirement                          | Tasks     | Coverage   |
|------|--------------------------------------|-----------|------------|
| R01  | User can log in with email+password  | T3, T4    | ✓ Covered  |
| R02  | Failed login shows error message     | T4        | ✓ Covered  |
| R03  | Passwords are stored hashed (bcrypt) | —         | ✗ Gap      |
| R04  | Session expires after 24 hours       | —         | ✗ Gap      |
| R05  | Supports OAuth2 login                | T7        | ~ Partial  |

Coverage status:

• ✓ Covered — at least one task explicitly addresses this requirement
• ~ Partial — a task addresses part of this requirement but leaves sub-requirements open
• ✗ Gap — no task addresses this requirement

---

Step 4 — Produce Gap Report

For every ✗ Gap or ~ Partial:

## Coverage Gaps

### Gap: R03 — Passwords are stored hashed (bcrypt)

**Requirement:** spec.md, Section 2.3 — "Passwords must be stored using bcrypt
with a minimum work factor of 12"

**Missing task:** No task in tasks.md creates or verifies password hashing logic.

**Suggested task addition:**
> Task N+1: Write test asserting stored password hash matches bcrypt format with
> work factor ≥ 12. Implement bcrypt hashing in the auth service. Verify
> no plaintext passwords appear in logs or database.

---

### Gap: R04 — Session expires after 24 hours

**Requirement:** spec.md, Section 2.5 — "Sessions must be invalidated after 24 hours"

**Missing task:** Session expiry logic has no corresponding test task.

**Suggested task addition:**
> Task N+2: Write test asserting session token is rejected after 24 hours.
> Implement expiry check in session middleware.

---

Step 5 — Check Task Quality

Beyond coverage, flag any task that has these quality issues:

| Quality Issue | Example | Flag | |---|---|---| | No test step | Task says "implement X" but has no "write failing test" step | ⚠ Missing TDD step | | Vague file path | "Update the auth module" with no specific file | ⚠ Missing file path | | Placeholder content | Task says "fill in details later" or "add appropriate handling" — open-ended directives with no concrete action | ⚠ Placeholder detected | | Multiple behaviors in one task | Task covers login AND logout AND session | ⚠ Overly broad | | No commit step | Task has no git commit at end | ⚠ Missing commit step |

---

Step 6 — Summary and Decision

Produce a summary:

## Coverage Review Summary

**Requirements extracted:** [N]
**Fully covered:** [A] ([A/N]%)
**Partially covered:** [B]
**Gaps identified:** [C]
**Task quality issues:** [D]

**Decision:**

If C > 0 (gaps exist):

⚠ GAPS DETECTED — Implementation should not begin until gaps are addressed.

Recommended action:
1. Review each gap above
2. Add missing tasks to tasks.md
3. Re-run coverage review OR proceed with explicit acknowledgment of scope reduction

If C == 0 and D == 0:

✓ COVERAGE COMPLETE — All requirements have corresponding tasks.
tasks.md is ready for implementation.

If C == 0 but D > 0:

⚠ QUALITY ISSUES — Coverage is complete but task quality issues may cause
TDD violations during implementation.

Recommended action: Fix flagged tasks before running speckit.implement.

---

Non-blocking Mode

If the user explicitly ran this review after acknowledging gaps, note the acknowledged gaps and proceed:

NOTE: [N] gaps were identified and flagged. Proceeding to implementation
with explicit acknowledgment. Gaps should be tracked as follow-on work.