run-sdlc

The full skill.

Original instructions from the publisher’s SKILL.md

# Run SDLC (navigator)

Owned by the **Orchestrator** (cross-cutting). Invoked as `/run-sdlc <artifact>`.

Given any work item or artifact, work out where it sits in the lifecycle and what comes next,
then report it. This is a **guide, not an autopilot**: it reads and reports; it never writes,
and by default does not execute the next step - the human decides whether to run it. On explicit
request it dispatches the next step per `docs/ai-sdlc/orchestration.md`, handing off to the owning
step-skill (which writes behind its own gates) and running genuinely independent steps in parallel
on Claude. It still does not author anything itself; it routes.

The phase/step/persona map this navigates is in `docs/ai-sdlc/plan.md`; the graph it traverses
(front-matter edges in local work item files and repo artifacts) is defined in `docs/ai-sdlc/artifact-graph.md`.
Read those for the authoritative map and schema rather than trusting a copy here.

## The lifecycle it reports against

Phases in order, with the governance track running across all of them:

- **discovery** - synthesize-research, map-journey, upsert-hypothesis-canvas (Analyst)
- **elaboration** - upsert-user-story, upsert-prd-document, upsert-user-story-acceptance-criteria, architecture, upsert-api-contract (PM / Architect)
- **create** - sprint-planning, code-generation, refactoring, verify-test-coverage, upsert-documentation (Scrum Master / Developer / QA / Tech Writer)
- **mature** - collect-release-feedback, analyze-ticket, resolve-ticket (PM / Developer)
- **governance** (cross-cutting) - constitution, author-adr, enrich-ticket, check-graph (Lead / Architect / any)

## Input

One of:
- a **local work-item key** (e.g. `MN-42`), the usual anchor;
- a **repo artifact path** (a doc, spec, or ADR) that declares `story:` front-matter;
- a free description, in which case resolve it to a key first (search `docs/discovery/`) or ask.

## Workflow (read-only)

1. **Resolve the anchor.**
   - Given a key (e.g. `MN-42`): find the matching work item file under `docs/discovery/` by scanning front-matter `key:` fields. Read its content (title, status, type, points, relates).
   - Given a repo path: read its front-matter (`story`, `phase`, `step`, `relates`) and take `story` as the anchor. If it has no front-matter, treat the file as not yet in the graph and say so.
2. **Traverse the graph (repo side).**
   - Find artifacts that declare `story: <key>` in a YAML front-matter block (the `story:` line between the leading `---` fences). Search `docs/`, `docs-functional/`, and `specs/`. Ignore the illustrative examples in `docs/ai-sdlc/*` (they show the schema, they are not real artifacts). Collect each artifact's `phase`, `step`, and `relates` edges (spec, adr, design, research, docs).
   - Read the work item file itself for `relates:` entries pointing to other work items (story-to-story edges), and for artifact links in its body sections (Decisions and ADRs, Artifacts and references).
3. **Place it in the lifecycle.** From the anchor's phase (front-matter, or inferred from status/type) and which artifacts exist, determine the current phase and which expected edges are present vs missing. Use the "intended required edges" in `docs/ai-sdlc/artifact-graph.md` as the checklist.
4. **Report (do not act).** Cover:
   - **Where it is:** the current phase and what exists (story, ACs, spec, ADRs, code/tests, docs), each with its path.
   - **What's missing:** the expected edges or artifacts not yet present. Mark an expected edge **N/A (reason)** rather than missing when the work plainly does not need it.
   - **Options:** a numbered list of the viable next `/<phase>-<step>` moves from here, each with the **persona** who owns it and a short why.
   - **Recommendation:** end with one recommended option and a short, concrete why it is the best move now.
   - **Thin ticket -> sharpen before build.** If the anchor is under-specced, recommend sharpening first.
   - **Entering build starts with a plan, not code.** When the next step is `/create-code-generation`, say so explicitly.
   - **Caveat:** the graph is incremental, so artifacts without front-matter are invisible here; say the report is "based on what is linked".
5. **Offer to dispatch.** By default, stop here. If the user asks you to run the next step, dispatch it per `docs/ai-sdlc/orchestration.md`.

## Output shape

A short report, for example:

```
MN-42  -  "Compare two cloud configuration versions"
Phase:   elaboration  (story exists, acceptance criteria present)
Linked:  story (docs/discovery/stories/cloud-config/compare-versions.md), ADR 0007 (docs/adrs/0007-...md)
Missing: machine-readable spec (relates.spec) before it can enter create

Options:
  1. /elaboration-upsert-api-contract          (Architect) - add the OpenAPI spec the build will consume
  2. /elaboration-upsert-user-story-acceptance-criteria (PM/QA)     - tighten the ACs first if any are still thin
  3. /governance-enrich-ticket        (any)       - link the spec/ADR onto the work item once they exist

Recommendation: 1, /elaboration-upsert-api-contract. The story is AC-complete but has no spec, and the spec is the gate into create.

(Based on linked artifacts; the graph is incremental, so unlinked work is not shown.)
```

## Guardrails

- **Read-only navigation.** The navigator never creates, edits, links, or transitions anything itself.
- **A guide, not an autopilot.** Do not run the next step automatically - surface it and let the human choose.
- **Be honest about coverage.** The graph is incremental; state that the report reflects only artifacts that have opted in (front-matter). Do not assert a phase is "done" from absence of evidence.
- **No direct writes.** No file creation, front-matter edits, or work item writes from the navigator itself. When the user wants to act, dispatch to the owning skill.

## Next steps

- Run the `/<phase>-<step>` this report identified, owned by the named persona.
- To run several genuinely independent next steps at once, dispatch them per `docs/ai-sdlc/orchestration.md`.
- If an expected edge is missing because it was never linked (not because the work is undone), fix the link with `/governance-enrich-ticket`, then re-run this navigator.
- `/governance-check-graph` (Lead) - validate that the repo-side `relates:` links actually resolve.