---
name: eck:ac-coverage
version: "0.7.4"
description: "AC-ID traceability dashboard — shows per-criterion lifecycle coverage across spec, design, develop, and validate phases."
disable-model-invocation: false
---

# AC Coverage

Display an AC-ID traceability dashboard for a feature. Shows which acceptance criteria have been specified, planned, implemented, and tested.

> **Read-only report.** This skill scans existing lifecycle documents — it does not modify them.

Report on: $ARGUMENTS

---

## Visual Framework

Follow the visual framework defined in the `output:visual-framework` primitive.

---

## Task Registration

| Stage | Subject         | Active Form        | Statusline   |
| ----- | --------------- | ------------------ | ------------ |
| 1     | Stage 1: Scan   | Scanning documents | Scan (1/2)   |
| 2     | Stage 2: Report | Building report    | Report (2/2) |

### Statusline Stage Updates

At the **start** of each stage, update the statusline:

```bash
bash $ECK_HOME/update-stage.sh "{Statusline text from table}"
```

At **skill completion** (success or error), reset:

```bash
bash $ECK_HOME/update-stage.sh
```

---

## Usage

```bash
/eck:ac-coverage <feature>                # Terminal dashboard only
/eck:ac-coverage <feature> --write        # Also write TRACEABILITY.md
/eck:ac-coverage <feature> --all          # Scan all features in docs/
```

### Flags

| Flag      | Description                                                              |
| --------- | ------------------------------------------------------------------------ |
| `--write` | Write the coverage report to `docs/{feature}/TRACEABILITY.md`            |
| `--all`   | Scan all feature directories under `docs/` and produce a combined report |

---

## Stage 1: Scan

```bash
bash $ECK_HOME/update-stage.sh "Scan (1/2)"
```

Locate and read all lifecycle documents for the target feature(s).

### Inputs

- `$ARGUMENTS` — feature description or slug, and flags
- `.claude/project-constants.md` — project key, paths
- Lifecycle documents in `docs/{feature}/`

### Activities

1. Read project constants from `.claude/project-constants.md`. If missing, warn and continue.

2. Parse `$ARGUMENTS` for the feature slug and flags (`--write`, `--all`).

3. If `--all` is specified, enumerate all feature directories:

   ```bash
   ls -d "$CLAUDE_PROJECT_DIR/docs/"*/ 2>/dev/null
   ```

   Otherwise, derive the feature slug from `$ARGUMENTS`:

   ```bash
   FEATURE_ID=$(node $ECK_HOME/manage-features.js resolve "$ARGUMENTS" 2>/dev/null | jq -r '.id // empty')
   [ -z "$FEATURE_ID" ] && FEATURE_ID=$(node $ECK_HOME/update-lifecycle.js read 2>/dev/null | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf-8'));console.log(d.active_feature||'')" 2>/dev/null)
   FEATURE_SLUG=$(node $ECK_HOME/manage-features.js read "$FEATURE_ID" 2>/dev/null | jq -r '.slug // empty')
   ```

4. For each feature, scan for lifecycle documents using the `traceability:coverage-report` primitive:

   ```bash
   # Check for each document
   test -f "$CLAUDE_PROJECT_DIR/docs/${FEATURE_ID}-${FEATURE_SLUG}/FRD.md" && echo "FRD.md found" || echo "FRD.md missing"
   test -f "$CLAUDE_PROJECT_DIR/docs/${FEATURE_ID}-${FEATURE_SLUG}/TASKS.md" && echo "TASKS.md found" || echo "TASKS.md missing"
   test -f "$CLAUDE_PROJECT_DIR/docs/${FEATURE_ID}-${FEATURE_SLUG}/DEV-NOTES.md" && echo "DEV-NOTES.md found" || echo "DEV-NOTES.md missing"
   test -f "$CLAUDE_PROJECT_DIR/docs/${FEATURE_ID}-${FEATURE_SLUG}/VALIDATION.md" && echo "VALIDATION.md found" || echo "VALIDATION.md missing"
   ```

   Also check parent-relative paths (some project layouts use `docs/plan/TASKS.md`):

   ```bash
   # Alternative locations
   find "$CLAUDE_PROJECT_DIR/docs/${FEATURE_ID}-${FEATURE_SLUG}" -maxdepth 2 -name "TASKS.md" -o -name "DEV-NOTES.md" -o -name "VALIDATION.md" 2>/dev/null
   ```

5. Read each found document. For each, extract the AC-ID references:
   - **FRD.md**: Parse `## Acceptance Criteria` table — extract AC-ID, Criterion (truncate to 40 chars), and Status
   - **TASKS.md**: Parse `### Acceptance Criteria Coverage` table — extract AC-ID to Task mapping. Parse `## Tasks` table — extract Task Status.
   - **DEV-NOTES.md**: Parse `## AC Coverage` table — extract Task to AC-ID mapping. Parse `### Uncovered AC` table.
   - **VALIDATION.md**: Parse `## AC Checklist` table — extract AC-ID to Result mapping (Pass/Fail/Partial).

6. If FRD.md is not found for a feature, skip that feature with a warning:

   ```bash
   source $ECK_HOME/colors.sh
   printf '%b\n' "${DIM}[-]${RESET} {feature} — no FRD.md found, skipping"
   ```

7. Print a scan summary listing all features scanned and documents found.

### Outputs

- Per-feature document inventory (which lifecycle documents exist)
- Extracted AC-ID data from each document
- Scan summary displayed

### Exit Criteria

- At least one feature with FRD.md found
- All available lifecycle documents read and parsed
- Scan summary displayed

---

## Stage 2: Report

```bash
bash $ECK_HOME/update-stage.sh "Report (2/2)"
```

Compute the coverage matrix and display the dashboard.

### Inputs

- Extracted AC-ID data from Stage 1
- Per-feature document inventory
- `--write` flag (if specified)
- `--all` flag (if multiple features)

### Activities

1. For each feature, compute the coverage matrix using the `traceability:coverage-report` primitive protocol:

   For each AC-ID in FRD.md, determine lifecycle status:

   | Column      | ✓ Condition                          | ◐ Condition              | - Condition                    |
   | ----------- | ------------------------------------ | ------------------------ | ------------------------------ |
   | Specified   | AC-ID exists with non-Retired status | —                        | Not in FRD.md                  |
   | Planned     | AC-ID mapped to task in TASKS.md     | —                        | Not in TASKS.md coverage table |
   | Implemented | Task in DEV-NOTES.md AC Coverage     | Task in progress         | Not in DEV-NOTES.md            |
   | Tested      | Pass in VALIDATION.md                | Partial in VALIDATION.md | Not in VALIDATION.md or Fail   |

   Retired AC-IDs show `⊘` in the Specified column and `-` in all other columns.

   Derive the overall Status for each AC-ID:
   - **Pass** — all 4 columns are `✓`
   - **In Progress** — at least Specified + Planned, but not fully tested
   - **Gap** — active AC-ID missing from one or more lifecycle phases
   - **Retired** — AC-ID has Retired status

2. Compute summary metrics (Retired excluded from denominators):
   - Total, Active, Retired counts
   - Planned / Active percentage
   - Implemented / Active percentage
   - Tested (Pass) / Active percentage
   - Full coverage (all 4 phases) / Active percentage

3. Identify gaps — active AC-IDs not fully traced:
   - List each gap AC-ID with the missing phase(s) and a recommended action:
     - Missing Planned → "Add task mapping in TASKS.md"
     - Missing Implemented → "Implement in a development session"
     - Missing Tested → "Run /eck:validate to verify"

4. Display the terminal dashboard:

   ```bash
   source $ECK_HOME/colors.sh

   echo ""
   printf '%b\n' "${ORANGE}${BOLD}AC-ID Traceability${RESET}"
   echo ""
   ```

   Then display the coverage matrix as a table:

   ```
   AC-ID  │ Criterion                    │ Spec │ Plan │ Dev  │ Test │ Status
   ───────┼──────────────────────────────┼──────┼──────┼──────┼──────┼────────────
   AC-1   │ Returns 200 on valid input   │  ✓   │  ✓   │  ✓   │  ✓   │ Pass
   AC-2   │ Rejects empty email field    │  ✓   │  ✓   │  ◐   │  -   │ In Progress
   AC-3   │ Stores audit log entry       │  ✓   │  -   │  -   │  -   │ Gap
   AC-4   │ Displays error toast on 500  │  ⊘   │  -   │  -   │  -   │ Retired
   ```

5. Display the summary box:

   ```bash
   printf '%b\n' "${ORANGE}${BOLD}Coverage Summary${RESET}"
   echo ""
   printf '%b\n' "Feature: {FEATURE_NAME}"
   printf '%b\n' "Total AC-IDs: {TOTAL} ({ACTIVE} active, {RETIRED} retired)"
   printf '%b\n' "Planned: {X}/{ACTIVE} ({PCT}%)"
   printf '%b\n' "Implemented: {Y}/{ACTIVE} ({PCT}%)"
   printf '%b\n' "Tested: {Z}/{ACTIVE} ({PCT}%)"
   printf '%b\n' "Full coverage: {W}/{ACTIVE} ({PCT}%)"
   echo ""
   ```

6. If gaps exist, display the gap table:

   ```bash
   printf '%b\n' "${BOLD}Coverage Gaps${RESET}"
   echo ""
   ```

   ```
   AC-ID  │ Missing Phase(s)       │ Action
   ───────┼────────────────────────┼──────────────────────────
   AC-3   │ Planned, Implemented   │ Add task mapping in TASKS.md
   AC-5   │ Tested                 │ Run /eck:validate to verify
   ```

7. If `--write` flag is present, write the report to `docs/{feature}/TRACEABILITY.md` using the `traceability/TRACEABILITY.md.template`:

   ```bash
   FEATURE_ID=$(node $ECK_HOME/manage-features.js resolve "$ARGUMENTS" 2>/dev/null | jq -r '.id // empty')
   [ -z "$FEATURE_ID" ] && FEATURE_ID=$(node $ECK_HOME/update-lifecycle.js read 2>/dev/null | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf-8'));console.log(d.active_feature||'')" 2>/dev/null)
   FEATURE_SLUG=$(node $ECK_HOME/manage-features.js read "$FEATURE_ID" 2>/dev/null | jq -r '.slug // empty')
   # Write TRACEABILITY.md with computed data
   test -f "$CLAUDE_PROJECT_DIR/docs/${FEATURE_ID}-${FEATURE_SLUG}/TRACEABILITY.md" && echo "[x] TRACEABILITY.md written" || echo "[!] Write failed"
   ```

   Display confirmation:

   ```bash
   source $ECK_HOME/colors.sh
   printf '%b\n' "${GREEN}[x]${RESET} Report written to docs/{feature}/TRACEABILITY.md"
   ```

8. If `--all` flag is present and multiple features were scanned, display an aggregate summary after the per-feature reports:

   ```bash
   printf '%b\n' "${ORANGE}${BOLD}Aggregate Coverage${RESET}"
   echo ""
   printf '%b\n' "Features: {N} scanned"
   printf '%b\n' "Total AC-IDs: {TOTAL} across all features"
   printf '%b\n' "Full coverage: {W}/{ACTIVE} ({PCT}%)"
   printf '%b\n' "Total gaps: {GAP_COUNT} AC-IDs"
   ```

9. Print next steps:
   ```
   Next steps:
   - Fill gaps: /eck:design {feature} (for unplanned ACs)
   - Verify: /eck:validate {feature} (for untested ACs)
   - Revise spec: /eck:spec {feature} (to retire obsolete ACs)
   ```

### Outputs

- Coverage matrix displayed in terminal for each feature
- Summary metrics displayed
- Gap analysis with recommended actions
- `TRACEABILITY.md` written (if `--write` flag)
- Aggregate summary (if `--all` flag)
- Next steps displayed

### Exit Criteria

- Coverage matrix displayed for at least one feature
- Summary metrics computed and displayed
- Gaps identified with recommended actions
- TRACEABILITY.md written if requested
- Statusline reset

---

## Error Handling

| Condition                            | Behavior                                                                                |
| ------------------------------------ | --------------------------------------------------------------------------------------- |
| No FRD.md found for feature          | WARN: "No FRD.md found for {feature}. Run `/eck:spec` first." Skip feature.             |
| No TASKS.md found                    | Display `-` for Planned column; note in Document Status                                 |
| No DEV-NOTES.md found                | Display `-` for Implemented column; note in Document Status                             |
| No VALIDATION.md found               | Display `-` for Tested column; note in Document Status                                  |
| `--all` finds no feature directories | STOP: "No feature directories found in docs/. Run `/eck:spec` to create one."           |
| AC-ID in TASKS.md not in FRD.md      | WARN: "AC-{N} referenced in TASKS.md but not found in FRD.md — orphaned reference."     |
| Malformed AC table in any document   | WARN: "Could not parse AC table in {document}. Skipping." Continue with available data. |

Follow the error display, gate failure, and statusline reset patterns defined in the `output:error-handler` primitive.

---

## Related Documents

- `traceability:coverage-report` — primitive defining the scanning and aggregation protocol
- `scaffold/templates/traceability/TRACEABILITY.md.template` — output template
- `output:visual-framework` — terminal output conventions
- `output:error-handler` — error display and statusline reset patterns
- `scaffold/global/skills/spec/SKILL.md` — generates FRD.md with AC-IDs
- `scaffold/global/skills/design/SKILL.md` — generates TASKS.md with AC-ID task mapping
- `scaffold/global/skills/develop/SKILL.md` — generates DEV-NOTES.md with AC coverage
- `scaffold/global/skills/validate/SKILL.md` — generates VALIDATION.md with AC checklist
