artifact-scan

Artifact Scan

A fast, read-only routine. Scan the repo for the product artifacts, report what exists, and point the user at exactly one next skill. No interview, no grilling, no writing. Just look, report, route.

Where this sits

PORTFOLIO — many features        ideate  or  chat-to-approach
                                        ↓
                            ./docs/approach.md  →  ./ideas/roadmap.html
                                                        ↓  pick ONE card
FEATURE — one feature per run    to-prd → to-scaffold → to-tickets → ticket-tracker
                                 non-code work: to-prd → to-tickets

The doors (ideate, chat-to-approach, or an already-scoped task) are optional ways in.
Portfolio → feature is a fan-out, not a step. A roadmap card is a feature — something to be built, which then breaks down into several tickets. Six cards means six runs down the spine, not one. When a skill is handed a portfolio artifact, it must establish which feature first.
Never send the user backwards. A missing upstream artifact is written inline or offered, never a reason to stop and run another skill first. The one hard gate is the merged scaffold PR.

That rule drives this skill's whole job: report what exists, don't compute a first gap. An earlier artifact being absent is not a problem to solve — it is usually a deliberate skip.

The artifacts

Artifact	Level	How to detect it	Skill that produces it
ideate report	portfolio	`ls ./ideas/reports/*-ideate.md`	`ideate`
approach doc	portfolio	`test -f ./docs/approach.md`	`chat-to-approach`
roadmap board	portfolio	`test -f ./ideas/roadmap.html`	`to-roadmap`
PRD	feature	`ls ./docs/prd-*.md` and `gh issue list` for `[PRD]`	`to-prd`
scaffold PR	feature	`gh pr list --state all --search scaffold` (merged = gate cleared)	`to-scaffold`
tickets	feature	`gh issue list` — any issue NOT titled `[PRD]`	`to-tickets`

Feature-level artifacts are countable, not binary. Three scaffold PRs means three features are mid-spine; it does not mean "the scaffold stage is done". Report counts and names, never a single tick.

Procedure

Scan local files in one pass:

ls ./ideas/reports/*-ideate.md ./docs/approach.md ./ideas/roadmap.html \
   ./docs/prd-*.md 2>/dev/null

Scan GitHub issues once, then split by title:
```
gh issue list --state open --limit 100 --json number,title 2>/dev/null
```
- PRDs: any title starting [PRD].
- Tickets: any open issue that is not a [PRD] issue.
- If gh is unavailable or errors (no remote, not authed), mark the GitHub-backed artifacts unknown, not absent — never guess. Say so in the report. Local ./docs/prd-*.md files still count as PRDs, so a repo with no remote can still show the PRD artifact present.
Report what you observed, citing the file path or issue number as evidence. Never report an artifact you did not see. Group by level so the user can tell portfolio work from feature work.

Route. Do not compute "the earliest gap". Ask what the user has and match it:

What the user has	Route to	Why
A scoped feature or a clear idea	`to-prd`	The spine starts here. Prior artifacts are optional accelerants
Nothing — no idea what to build	`ideate`	The only door that generates an idea from the codebase
A conversation from claude.ai or elsewhere	`chat-to-approach`	Captures the handoff into `approach.md`
An approach doc, wants to prioritise	`to-roadmap`	Turns many features into Now / Next / Later
A roadmap, wants to start building	Pick one card → `to-prd`	Each card is its own spine run
A PRD for a code feature	`to-scaffold`	Opens the scaffold PR that gates ticket cutting
A PRD for non-code work, or a merged scaffold PR	`to-tickets`
Tickets already filed	`ticket-tracker`	Move them through the board

When the invocation itself makes the intent obvious, route on that and say so — a user who describes a feature is not asking to ideate, even on an empty repo.

If you genuinely cannot tell which of two doors applies, ask one question via AskUserQuestion rather than guessing. Recommend exactly one skill.

Report format

Product artifacts

  Portfolio (many features)
    [x] ideate report  — ./ideas/reports/2026-05-01-ideate.md
    [x] approach doc   — ./docs/approach.md
    [ ] roadmap        — not found

  Feature (per feature)
    [x] PRDs           — 2: ./docs/prd-search.md, #41 [PRD] Saved views
    [x] scaffold PRs   — 1: #44 scaffold search (merged)
    [?] tickets        — unknown (gh unavailable)

Next: `to-scaffold` — "Saved views" has a PRD but no scaffold PR yet.

Use [x] present, [ ] absent, [?] unknown. Always list all six so the user sees the whole suite. Close with one line naming exactly one skill and the reason.

Absent portfolio artifacts are not a finding. Do not tell the user to go back and write an approach doc because one is missing — say what is missing, then let the routing table decide.

Notes

Read-only. This skill never creates or edits artifacts — it only reports and routes.
When invoked as a preflight by another skill, return the artifact map and skip the prose framing and the routing verdict — the calling skill does its own routing.