Skill Audit: Every /ds-* Skill

This is the complete reference for the /ds-* Claude Code skills — one entry per skill, with how you invoke it, the argument it accepts, and what it does. The two loop pages (The Planning Loop and The Delivery Loop) tell the story of how these skills chain together; this page is the flat index you scan when you just need to know what one skill is and how to call it.

Every skill lives at .claude/skills/<name>/SKILL.md in the devstride repo, is invoked as a slash command (/ds-plan, /ds-build-item, …) or picked up automatically by name/description, and — where it matters — reads its repo-specific values from .claude/ds-config.json. If any of the terms below are unfamiliar, start with Claude Code Skills: AI-Assisted Development for the what-and-why and the shared safety model.

At a glance

Notation: <required>, [optional], a | b are alternatives. I#### is a DevStride item number (e.g. I11024); F#### is a workstream/folder.

Planning skills

Skills that shape the roadmap — Capabilities, Epics, Stories, and the dependency graph — before any code is written. Narrative: The Planning Loop.

/ds-plan

• Invoke: /ds-plan <parent-item> [description] · writes live data (after sign-off)
• Argument: a parent item number to plan under — a Module, Capability, or Epic (e.g. I10992) — optionally followed by a short description of what's being planned. Empty → it asks which item to plan under rather than guessing.
• What it does: drives a full Capability → Epic → Story hierarchy into existence through an interactive, loop-based discovery process (not a one-shot generator). It comprehends what already exists, asks scope/sequencing/risk questions in rounds, and only after an explicit "yes, build this" sign-off creates the items — wiring every Story into a real blocked_by/blocks graph (zero orphans), stamping execution-order [N] title prefixes, and finishing by calling /ds-rationalize-gantt to date the plan. The judgment calls always happen in the conversation; only bulk drafting is fanned out to Workflows.

/ds-comprehend-plan

• Invoke: /ds-comprehend-plan <item> [focus question] · read-only
• Argument: the plan root to comprehend (e.g. I10992), optionally followed by a focus question such as what's left before webhook intake is done?. The question sharpens the synthesis but never narrows what gets read.
• What it does: recursively reads a plan's descriptions and every comment, at every level, to build a grounded picture of what a Module/Capability/Epic actually contains and where it stands. Comments carry the as-built history that descriptions often miss, so a description-only pass doesn't count as comprehension. It never mutates anything — other skills call it first (e.g. /ds-plan step 1) to avoid clobbering an existing plan, and you run it standalone whenever the plan's state is unclear.

/ds-insert-story

• Invoke: /ds-insert-story [parent-item] <description> · writes live data
• Argument: free text describing the story, optionally prefixed/suffixed with the parent Module/Capability/Epic number (e.g. I10992 add rate limiting to webhook intake, or just the description if there's no ambiguity).
• What it does: splices one new Story into a live plan's dependency chain — positioned so /ds-build-item picks it up next, with an honest spec (never a fabricated "always planned" backstory). It confirms the Gantt auto-scheduler is off before wiring edges, sets priority so the item wins its date tier, and re-derives what /ds-build-item would actually pick next rather than assuming the splice worked. It does not re-date the rest of the plan — that's a separate /ds-rationalize-gantt call.

/ds-insert-defect

• Invoke: /ds-insert-defect [parent-item] <description> · writes live data
• Argument: same shape as /ds-insert-story — free text describing the defect, optionally anchored to a parent item.
• What it does: nearly identical to /ds-insert-story, but for bugs, with an honest repro/root-cause description. It has one extra behavior: a defect often needs to jump ahead of already-planned Stories because it's blocking something real — the skill states the case and gets your explicit confirmation before queue-jumping, rather than silently reprioritizing the roadmap.

/ds-rationalize-gantt

• Invoke: /ds-rationalize-gantt <plan-root> · writes live data (overwrites dates)
• Argument: the item number whose descendant tree is the plan (a Solution/workstream/Epic, e.g. I10992), or a roadmap/Gantt name. Empty → it asks which plan.
• What it does: backfills synthetic one-story-per-day dates and rationalizes the dependency graph so the Gantt renders as a maximally compressed, gapless, fully valid cascade (a synthetic critical-path view, not a real-world forecast). It overwrites existing start/due dates across the tree, so it confirms up front whether to re-date completed items too. Non-negotiable prerequisite: the Gantt dependency auto-scheduler must be OFF (there's no API flag) — it asks you to toggle it in the UI, then verifies with a probe write + read-back before any mass write.

The delivery loop

Skills that carry code from a selected item to merged-and-Done. Narrative: The Delivery Loop.

/ds-build-item

• Invoke: /ds-build-item <item | next | under I####> · writes live data (lane moves, links)
• Argument: a DevStride item number (e.g. I11024); next/empty to pick the next unblocked item; or a plan root to scope selection (next under I10992, or I10992 alone). A specific item that isn't part of a sequenced plan is auto-detected as a one-off and built single-shot.
• What it does: the orchestrator. It runs the whole loop — select → mark In Progress → branch → build → adversarial review → PR → merge → completion ritual → sync → next — composing the skills below and owning only the DevStride glue (next-item selection, lane transitions, the completion ritual). Designed to run under /loop for full autonomy, pausing only at a genuine fork. It auto-detects plan-loop mode (walk a sequenced plan) vs one-off single-shot mode (ship one standalone item once and terminate), and supports an opt-in integration-branch working base for large initiatives.

/ds-create-story

• Invoke: /ds-create-story <description> · writes live data
• Argument: free text describing the story, optionally prefixed/suffixed with a parent item (I####) or workstream (F####), e.g. I10992 add rate limiting to webhook intake.
• What it does: the one-off entry point for an inbound request that isn't part of any plan. It requires enough detail to write an honest one-paragraph spec (asking if the ask is too thin), asks where in the map and which board to file it, assigns it to the current user, creates the Story, then hands straight to /ds-build-item's single-shot mode to deliver it once — no chain splice, no [N] numbering. Use /ds-insert-story instead when the work belongs in a sequenced plan.

/ds-create-defect

• Invoke: /ds-create-defect <description> · writes live data
• Argument: free text describing the bug, optionally anchored to a parent I#### / F####, e.g. I10992 webhook retries duplicate on 429.
• What it does: the one-off sibling of /ds-create-story, for an inbound bug not in any plan. It requires a real repro (expected-vs-actual) before acting, files the Defect under the container that owns the broken behavior on a board, assigns it to the current user (isBug: true), then delivers it single-shot via /ds-build-item. Use /ds-insert-defect when the bug belongs in a plan's chain.

/ds-branch-feature

• Invoke: /ds-branch-feature <branch-name> · git only
• Argument: a short branch-name suffix, typically I<number>-<short-slug> (e.g. I11024-seat-invariant).
• What it does: the everyday branch-creation utility. It aborts on a dirty tree, syncs the working base (develop by default, or the initiative's integration branch when /ds-build-item passes one), creates a branch named <user-prefix>/<MM-DD-YY>/<suffix>, and pushes it with -u. Used both standalone and as /ds-build-item step 2.

/ds-branch-hotfix

• Invoke: /ds-branch-hotfix <branch-name> · git + destructive local DB reset
• Argument: a short branch-name suffix (named <user-prefix>/hotfix/<MM-DD-YY>/<suffix>).
• What it does: a heavier, standalone tool for genuine production emergencies — it branches off a fresh master so the fix is built against what's actually running. Strict preflight: SOURCE_DB_CONNECTION_STRING must be set and the tree clean. Steps: checkout master → pull → the destructive ds script reset-db (drops and reseeds the local DB from prod) → create the branch → ds migrations run → push. On any failure it reports which step broke rather than stranding you on master. /ds-build-item never calls it.

/ds-ultracode-build

• Invoke: /ds-ultracode-build I#### <one-line goal/scope> · git + Workflows
• Argument: a DevStride item number plus a one-line scope (e.g. I11045 enforce the seat-count invariant in the subscription service). It assumes the branch already exists and the item is already In Progress.
• What it does: the build engine /ds-build-item invokes once a branch exists. Three phases: UNDERSTAND (for a substantive story, an ultracode Workflow of parallel reader agents → a concrete build plan + buildable-now-vs-deferred scope), BUILD (small increment → checks green → commit, repeated, with generated artifacts committed separately), and ADVERSARIAL REVIEW (a Workflow of parallel finders → per-finding verify → fix CONFIRMED/PLAUSIBLE, drop REFUTED). It opens no PR and merges nothing — it hands back a summary, deviations list, and untracked-deferral list.

The review stack: /ds-pr → /ds-pr-review → /ds-review

Three skills, each owning one layer, each usable standalone.

/ds-pr

• Invoke: /ds-pr [item-number] · writes live data (linking only)
• Argument: an optional DevStride item number (e.g. I11345) used when linking the PR to its item.
• What it does: owns PR creation and linking. It opens the PR with the required four-section description (Simple ELI5 Description · Technical Description · Notable Changes to System Architecture or Behavior · Testing Steps) — no --fill, and no AI-attribution text in the body — then delegates all review and CI gating to /ds-pr-review. Standalone it asks the base branch and offers to link the item; driven by /ds-build-item the base is pre-answered and linking is left to the loop.

/ds-pr-review

• Invoke: /ds-pr-review [PR#] · git + GitHub
• Argument: a PR number (e.g. 1234); empty → the current branch's open PR.
• What it does: the review + CI-gating policy for an open PR. It composes /ds-review for the mechanics and adds two rules of its own: adversarial review is a first-class gate (for every Codex/Copilot comment: evaluate → fix → reply with the implemented solution → mark the thread Resolved), and the long-running golden-build gate is deferred until all review comments are settled, since each review-fix push invalidates a prior golden run.

/ds-review

• Invoke: /ds-review [PR#] · git + GitHub
• Argument: a PR number (e.g. 2667); empty → the current branch's open PR.
• What it does: the reusable review engine. It launches the native /code-review and the repo's automated reviewers (Codex, Copilot) in parallel, waits interruptibly, de-dupes and verifies every finding against the real code, triages each into fix / dismiss-with-rationale / capture-out-of-scope / ask-on-fork, applies fixes via /ds-push, replies to and resolves every addressed thread, and settles CI to green. Standalone it notifies when the PR is ready; driven, it hands its findings back to the caller.

/ds-push

• Invoke: /ds-push · git only
• Argument: none.
• What it does: a small git utility — git add -u (tracked files only; never git add .), show status + a staged diff summary, commit with the session's required trailers, run the type-checks, then push (falling back to --force-with-lease, never a bare --force, on a non-fast-forward). If the type-check fails with non-SDK errors it does not push; it reports and asks. It never opens a PR — it's the push building block /ds-review calls to land fixes, and is equally usable standalone.

Golden dataset & local DB support skills

Supporting infrastructure a developer runs by hand — none of these is part of the /ds-build-item loop. They keep your local database and stage data usable while you build. For what the underlying CLI verbs do, see Golden Dataset.

/ds-golden

• Invoke: /ds-golden [org] · CLI (starts read-only)
• Argument: an optional persona org to scope to (acme | bright | indie | brightTrial); otherwise all golden orgs.
• What it does: checks golden-dataset health on the bound stage and, if needed, restores it. It always starts read-only (ds golden status, which mutates nothing); if the dataset is unhealthy it only proposes a fix (a re-import, a reanchor) for you to confirm — it never auto-runs a mutating verb on its own judgment.

/ds-golden-build

• Invoke: /ds-golden-build [representative | full] · CLI (heavy)
• Argument: representative (default, ~2 min, the ~110-item profile — a fast sanity build) or full (the ~21k-item profile, multi-hour — what actually ships to the source DB).
• What it does: the heavy content-authoring flow — rebuilds the dataset from the generator (backend/tests/golden/) and, once it passes the §16 pre-ship assertion gate, optionally publishes it to the canonical golden source DB. It touches no stage.

/ds-golden-push

• Invoke: /ds-golden-push <stage> · CLI (stage-aware, safe by construction)
• Argument: the target stage — dev (shared staging: additive import only), a disposable personal/CI stage (import or a full reset), or prod (refused).
• What it does: deploys/refreshes the golden Acme dataset onto a named stage, choosing the safe verb for that target (additive ds golden import for a populated shared stage; a whole-DB reset only for a confirmed-disposable one). It hard-refuses prod — the CLI's own stage guard blocks every mutating golden verb against production, and this skill won't attempt a workaround.

/ds-reset-db

• Invoke: /ds-reset-db · destructive local DB reset
• Argument: none.
• What it does: resets the local database from production, then re-applies the current branch's migrations on top. Strict preflight: SOURCE_DB_CONNECTION_STRING must be set, the tree should be clean, and it recommends stopping any running ds run backend first. If any step fails it checks out your original branch to restore you before reporting what broke.

Repo configuration & portability

The delivery skills externalize every repo-specific value — branches, verify/test/lint commands, generated-file paths, the local review command, and the automated reviewers — to a single checked-in file, .claude/ds-config.json, which they treat as authoritative over any literal shown inline. The planning skills read nothing from it (they self-resolve org config through the DevStride MCP at runtime), so they're portable as-is. See The Delivery Loop → Repo configuration for the full field list and the porting story.

Next Steps

• The Planning Loop — how /ds-plan and the insert/comprehend/rationalize skills shape the dependency graph
• The Delivery Loop — how /ds-build-item composes the branch/build/review skills to ship one item
• Claude Code Skills: AI-Assisted Development — the what, the why, and the production-write safety model