score

Files (1)

• SKILL.md

SKILL.md (first lines)

# Score

Manual surface for the [`reviewer-gates`](../../spec/features/reviewer-gates/README.md) dispatch pipeline. Implements the [Score Command Feature](../../spec/features/score-command/README.md) (Phase 1 of the [`manual-review-and-score-commands`](../../spec/ideas/manual-review-and-score-commands.md) Idea).

Producer category: **NOT a Producer.** This is a *signal skill* — it produces no canonical artifact under `spec/`. Read-only on `spec/`; writes nothing; emits no events. The Feature's `REQ: no-file-writes` and `REQ: no-new-config` are load-bearing — do not violate them under any circumstances.

## When to Use

- Mid-iteration self-review before re-running a producer skill (which would emit events and update status).
- Audit of an artifact the user did not author.
- Triage across the spec tree to find what needs attention next.
- Pre-PR sanity check on a draft the user paused on.

Do NOT invoke this skill in response to any producer-skill event (`feature.specified`, `idea.approved`, `plan.approved`, etc.). Manual invocation is the only entry point. (`REQ: invocation-triggers`.)

## Anti-Patterns

- **Carrying reviewer logic inside this skill.** Reviewers come exclusively from `gates.<stage>.reviewers` in `specscore.yaml`. No hardcoded baseline. No silent injection. No fallback. (`REQ: reuse-reviewer-gates-pipeline`.)
- **Writing any file under `spec/`, `.specscore/`, or any other repo path.** This skill is read-only. (`REQ: no-file-writes`.)
- **Emitting a SpecStudio event, or writing a file, on the default run.** The default `/score` run is ephemeral. Persistence happens only under the explicit opt-in flags `--save` (report) and `--badge` (badge injection), and manual runs propose the write and ask before applying it. (`REQ: no-file-writes`.)
- **Adding a new key to `specscore.yaml` or any new dotfile or environment variable.** All reviewer behavior is governed by the existing `gates:` block defined by `reviewer-gates`. (`REQ: no-new-config`.)
- **Suspending the user's session waiting for a `type: human` reviewer.** Skip those silently with a one-line note per artifact. (`REQ: human-reviewers-skipped`.)
- **Refusing the invocation when `gates:` is absent.** This skill is a signal skill, not a gate. Report every artifact as skipped, exit zero with the no-verdict warning. (`REQ: missing-gates-block-handling`.)

## Invocation Shape

```
specstudio:score [PATHS...] [-r|--recursive] [--against REF] [--verbose] [--yes]
```

| Argument / Flag | Semantics |
|---|---|
| `PATHS...` (positional, optional) | Files, directories, or glob patterns relative to repo root (or absolute). Empty list → defaults to `spec/`. |
| `-r`, `--recursive` | Descend into sub-artifacts beneath directory entries. Without this flag, sub-artifacts MUST NOT be included. |
| `--against REF` | Diff baseline supplied to `type: ai` reviewers. Default: `HEAD`. |
| `--verbose` | In multi-artifact mode, print per-artifact detail in addition to the summary table. No-op in single-artifact mode. |
| `--yes` | Skip the threshold confirmation prompt regardless of resolved-artifact count. Does NOT skip any other confirmation. |

Any unknown flag (anything starting with `-` that is not in the table above) MUST cause the skill to refuse to run with a usage error and exit non-zero. Do NOT silently ignore unknown flags. (`REQ: invocation-shape`.)

## Pipeline Overview

1. **Parse arguments** — fail fast on unknown flags.
2. **Resolve paths** — empty → `spec/`; directories → `README.md`; globs → shell expansion; `-r` → recursive descent; deduplicate; preserve first-appearance order.
3. **Map each artifact to a stage** — `spec/ideas/` → `ideate`; `spec/features/<slug>/README.md` → `specify`; `spec/plans/` → `plan`; anything else → skipped.
4. **Confirm-at-threshold** — if `-r` AND resolved count > 10 AND no `--yes`, prompt for explicit approval before dispatch.
5. **Per-artifact, in resolved order, serially**:
   1. Load `gates.<stage>.reviewers` via the shared loader.
   2. Filter out `type: human` entries; record a one-line skip note per artifact.
   3. Compute the unified diff `git diff <REF> -- <artifact-path>`.
   4. Dispatch surviving `type: ai` entries via the shared runner, passing the artifact body + diff to each.
   5. Collect the verdict (`Approved` | `Issues Found`).
6. **Emit output** — per-artifact detail (single-artifact) or summary table + footer (multi-artifact, with `--verbose` adding per-artifact detail).
7. **Exit** — zero if every reviewed artifact returned `Approved`, non-zero if any returned `Issues Found`, zero with no-verdict warning if every artifact was skipped.

The skill writes nothing in `spec/`; emits no events. The single user-facing side effect is the terminal output and the exit code (plus the report/badge only under `--save` / `--badge`).

> **Grade dependency.** The verdict this skill surfaces is whatever the shared reviewer-gates runner returns. The steps below describe the `Approved | Issues Found` shape that `reviewer-gates` returns today. Once `reviewer-gates` ships the grade as its verdict currency — the findings → A–F aggregation plus the configurable Approve threshold (default `B`) — this skill surfaces that grade and derives `Approved` as `grade ≥ threshold`, with no change to path resolution, dispatch, or the no-writes guarantee below.

## Step 1 — Parse Arguments

Tokenize the invocation. Distinguish positional `PATHS` from flags.

- Anything starting with `-` is a flag. The recognized flags are exactly `-r`, `--recursive`, `--against`, `--verbose`, `--yes`. Unknown flags MUST refuse the invocation. (`REQ: invocation-shape`.)
- `--against` MUST take a value (`--against REF` or `--against=REF`). A bare `--against` without a value MUST refuse.
- `-r` and `--recursive` are equivalent.
- `--verbose`, `--yes` are boolean flags.
- Everything else is a positional `PATHS` entry, in user-supplied order.

If parsing fails, print a one-line usage error and exit non-zero. Do not proceed to path resolution.

## Step 2 — Resolve Paths

The output of this step is `resolved_paths` — an ordered, deduplicated list of artifact paths, each tagged with whether it was skipped (and why) before any reviewer dispatch.

### 2a — Default empty PATHS

If `PATHS` is empty, treat it as the single entry `spec/`. (`REQ: empty-paths-default`.)

### 2b — Expand each PATHS entry, in user-supplied order

For each entry `p` in `PATHS`:

1. **If `p` contains a glob character (`*`, `?`, `**`)**: expand using shell-glob semantics against the repo working tree. If the expansion produces zero matches, refuse the entire invocation with `Error: glob pattern '<p>' matched no files in the working tree`; exit non-zero. (`REQ: glob-expansion`.) Add each expansion result (in lexicographic order) to the working list, marked as a "file" entry — globs do NOT recurse on their own.

2. **Else if `p` resolves to a directory**:
   - If `<p>/README.md` exists, add `<p>/README.md` to the working list, marked as a "directory-readme" entry.
   - If `<p>/README.md` does NOT exist, record the directory as **skipped** with reason `(no README.md in directory)` and continue with remaining entries. (`REQ: directory-resolves-to-readme`.)
   - If `-r` is supplied, ALSO add (after the README) every reviewable sub-artifact beneath `<p>` per the patterns in `artifact-to-stage-mapping` (Step 3), in lexicographic order. (`REQ: recursive-descent`.) Reviewable patterns are:
     - `<p>/ideas/*.md` (excluding `<p>/ideas/README.md`)
     - `<p>/ideas/seeds/*.md`
     - `<p>/features/*/README.md`
     - `<p>/plans/*.md` (excluding `<p>/plans/README.md`)

3. **Else if `p` resolves to a regular file**: add `p` to the working list, marked as a "file" entry. `-r` is a no-op for file entries (a file has nothing beneath to recurse into) — accept silently per the Feature's Not Doing list.

4. **Else** (`p` does not resolve): refuse the entire invocation with `Error: path '<p>' does not exist`; exit non-zero. (Globs are handled in step 1; reaching this branch means a literal path that does not resolve.)

### 2c — Deduplicate, preserving first-appearance order

Walk the working list. Build `resolved_paths` by appending each entry the first time it appears (key = absolute path of the artifact). Subsequent appearances of the same absolute path MUST be dropped. The order in `resolved_paths` is the order of FIRST appearance in the working list. (`REQ: deduplication-and-order`.)

## Step 3 — Map Each Artifact to a Stage

For each entry in `resolved_paths`, compute its stage using the canonical mapping (`REQ: artifact-to-stage-mapping`):

| Path pattern (relative to repo root) | Stage |
|---|---|
| `spec/ideas/<slug>.md` (not `spec/ideas/README.md`) | `ideate` |
| `spec/ideas/seeds/<slug>.md` (not `spec/ideas/seeds/README.md`) | `ideate` |
| `spec/features/<slug>/README.md` | `specify` |
| `spec/plans/<slug>.md` (not `spec/plans/README.md`) | `plan` |

Any other path — including index `README.md` files at `spec/README.md`, `spec/features/README.md`, `spec/ideas/README.md`, `spec/plans/README.md`, and anything under `spec/research/` — MUST be tagged **skipped** with reason `(no gate configured for this artifact type)`. Do NOT dispatch any reviewer for skipped artifacts. Continue with remaining entries.

## Step 4 — Confirm-at-Threshold

After Step 3, count the artifacts that are NOT yet tagged skipped — call this `reviewable_count`.

From specscore/specstudio-skills, MIT.

More from specscore/specstudio-skills