report

name	report
description	Survey the whole spec tree: what is complete, in progress, blocked, and actionable next. Reads the spec files, task files, and git history rather than any hand-maintained table. Read-only. Use for "where do things stand"; use validate to check the tree is structurally sound.

Spec Tree Report

Generate a live status report by reading specs, task files, and git history. If a specific spec is given, report on that spec only. Otherwise, report across all specs.

Step 0: Parse arguments

If an argument is provided, treat it as a spec file path for focused status. Otherwise, report on the full project.

Step 1: Discover specs and tasks

1. Glob for all spec files recursively: specs/**/*.md (excluding README.md). Specs are grouped by track: a directory under specs/ where one exists, otherwise the track: frontmatter field. An NNN- filename prefix is an independent, per-directory ordering convention — report in that order where it is present, but never read it as the dependency order. Take the track set from what is on disk, never from a list memorized here or in an earlier run.
2. For each spec, parse YAML frontmatter to extract title, status, depends_on, affects, effort, dispatched_task_id, and track (where the path does not already supply it).
3. Determine parent-child relationships from the filesystem: a spec at specs/<track>/foo.md with a directory specs/<track>/foo/ is a non-leaf spec; its children are the specs inside that directory.
4. Read specs/README.md for track organization and dependency context.

Step 2: Classify each spec

For each spec file, use the frontmatter status field as the primary source of truth:

1. Read the status from frontmatter: vague, drafted, validated, testing, complete, stale, or archived. testing is the transient drift-verdict state (implementation landed, awaiting the verdict) — report it as "in testing", and surface testing_pending if set (the drift tester is stuck). An archived spec is retired from the live graph — read-only, hidden by default, and excluded from progress, impact, drift, and dispatch.
2. For non-leaf specs (those with a child directory), compute progress by recursively counting leaf specs in the subtree:
   • Count leaves with status: complete vs total leaves.
   • Report progress as N/M leaves done (X%).
   • Archived leaves contribute 0 to both done and total.
   • An archived non-leaf masks its entire subtree from progress — ancestors aggregate nothing from an archived branch.
3. For leaf specs, check dispatched_task_id to see if the spec has been dispatched to the board. If dispatched, cross-reference the task status if possible.
4. Cross-check with codebase — for specs that claim complete, optionally verify the affects paths exist and look implemented. For specs that claim validated but may be partially done, check git log for commits referencing the spec or its affects paths.

Step 3: Check dependencies

For each non-complete spec:

1. Read the depends_on list from frontmatter. Each entry is a path to another spec file.
2. For each dependency, check its frontmatter status. A dependency is met only when its status is complete.
3. Flag specs that are actionable — status is validated, all depends_on entries are complete, and the spec is a leaf (or has a child breakdown ready). archived specs are never actionable — do not count them in blocked or unblocked totals.
4. Flag specs that are blocked — at least one depends_on entry is not complete.
5. Flag specs that are stale — their status is stale and they need human review before proceeding.

Step 4: Identify what's next

From the actionable specs, determine the recommended next steps:

• Validated leaf specs (small enough to build in one pass) → /spec:implement directly; it builds and finalizes (delegating to /spec:wrapup).
• Large specs ready to decompose → /spec:breakdown <spec> tasks first, then dispatch the leaves.
• Specs in testing (verdict pending) → /spec:wrapup to render the drift verdict (testing → complete/stale).
• Specs that need updating → suggest /spec:refine first.
• To advance a spec hands-off through the whole lifecycle → /spec:drive <spec> (pair with a /goal to run it autonomously to complete).

Step 5: Generate report

For a single spec:

## Status: <title> (<spec-path>)

Status: <frontmatter status>
Track: <track>
Effort: <effort>
Progress: N/M leaves complete (X%)  [for non-leaf specs]
Blocked by: <nothing or list of incomplete depends_on entries>
Affects: <list of code paths from frontmatter>

### Child Specs  [if non-leaf]
| Spec | Status | Effort | Depends on |
|------|--------|--------|-----------|
| <title> | complete | small | — |
| <title> | validated | medium | <sibling> |

### Next Action
<what to do next for this spec>

For the full project:

Group specs by the tracks discovered in Step 1 — one section per live track, in the order specs/README.md presents them — then by lifecycle state within each track:

## Project Status

### <track>
- <spec-name> (complete) — <one-line summary>
- <spec-name> (validated, 3/5 leaves done) — <progress note>

### <next track>
- <spec-name> (drafted) — <one-line summary>

### Actionable (ready to implement)
- <spec-name> — validated, all depends_on complete, <has/needs> child breakdown

### Blocked
- <spec-name> — waiting on: <depends_on list with statuses>

### Stale (needs review)
- <spec-name> — <reason for staleness or last updated date>

### Archived (hidden by default)
- <spec-name> — retired from the live graph; resurrect via `archived → drafted` transition

### Recommended Next Steps
1. <most impactful actionable item>
2. <second priority>
3. <third priority>

Notes

• This skill is read-only. It does not modify any files.
• Status is derived from source of truth (files, git), not from manually maintained tables in README.md.
• If the report reveals that specs/README.md status is stale, note the discrepancies but do not fix them (suggest /spec:refine or manual update).