Wf Spec Report

---
name: wf-spec-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.
argument-hint: [spec-file.md]
allowed-tools: Read, Grep, Glob, Agent, Bash(git log *), Bash(ls *)
---

# 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, not from a list remembered from 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) → `/wf-spec-implement`
  directly; it builds and finalizes (delegating to `/wf-spec-wrapup`).
- Large specs ready to decompose → `/wf-spec-breakdown <spec> tasks` first, then
  dispatch the leaves.
- Specs in `testing` (verdict pending) → `/wf-spec-wrapup` to render the drift
  verdict (`testing → complete`/`stale`).
- Specs that need updating → suggest `/wf-spec-refine` first.
- To advance a spec hands-off through the whole lifecycle → `/wf-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 `/wf-spec-refine` or manual update).