Doccraft Close

---
name: doccraft-close
description: >-
  Close a story end-to-end — flip its status to a terminal value and reconcile
  every downstream artifact in one pass: the backlog Status cell, the
  {{DOCS_DIR}}/queue.md row, the parent epic table (when the project uses
  epics), then a queue-audit reconcile. Use whenever the user says "close",
  "mark done", "ship", "finish", "complete", or "resolve" a story / ticket /
  backlog item, or moves work to a terminal state (done, done-no-promote,
  abandoned, absorbed). Reach for this instead of hand-editing the story file
  alone — a half-applied close (status flipped but queue/backlog/epic left
  stale) is exactly the drift this skill exists to prevent. Works for single-root
  and monorepo projects.
---

# doccraft — close a story (transactional)

## When to use

- The user wants to **close / ship / finish / resolve** a specific story and
  have the planning surface end up consistent — not just the story file.
- Work is moving to any **terminal** state: `done`, or a non-promoting
  terminal like `done-no-promote`, `abandoned`, `absorbed`.
- The user pastes "mark P1.30 done", "close audio-engine/STR-0042", "we
  shipped the retry flow", or similar.

Not for: authoring or re-scoping a story (use `doccraft-story`), a general
"what's unblocked / fix the queue" sweep with no specific story to close
(use `doccraft-queue-audit`), or recording a decision (use `doccraft-adr`).

Closing a story is a multi-file transaction. The story file is only step
one; the backlog row, the queue row, and (with epics) the parent epic table
all describe the same work and drift the moment one is updated without the
others. This skill owns the whole transition so a close never lands halfway.

## Configuration

Read `doccraft.json` at invocation. Every key below has a default in this
body, so a missing config file is a soft fallback, not an error.

- `docsDir` — root folder for all docs. Default: `docs`. Stories, queue, and
  backlog live at `{docsDir}/stories/`, `{docsDir}/queue.md`,
  `{docsDir}/backlog.md`.
- `story.status` — the allowed `status:` values. The **terminal** values are
  whichever of these mean "no longer active work" — `done` always, plus any
  the project adds (`done-no-promote`, `abandoned`, `absorbed`). Read this
  list rather than assuming `done` is the only terminal state; a story closed
  as `absorbed` is just as closed as one marked `done`.
- `queue.tables.suggestedOrder`, `queue.tables.platformSpikes` — heading text
  used to locate the queue tables. Defaults: `Suggested order`, `Platform
  spikes`. Matched on heading text, not row position.

## Multi-package scope

<!-- doccraft:packages -->
<!-- /doccraft:packages -->

For monorepo projects (a **Known package roots** block appears above when
packages are declared), a story lives under a specific scope — the project
root or a declared package's `{{DOCS_DIR}}/`. For single-root projects no
block appears and everything operates on the project-root `{{DOCS_DIR}}/`.

Resolve the target's scope before touching anything:

- **Namespaced id.** `pkg/STR-NNNN` names the package directly — operate in
  that package's `{{DOCS_DIR}}/`. An unprefixed id is project-root scoped.
- **Explicit `package:` arg.** Honour it.
- **Active-file inference.** If the user is editing a file under a declared
  package path, default to that package.

Close the story in **its own** scope: its story file, its package
`{{DOCS_DIR}}/queue.md`, and its package `{{DOCS_DIR}}/backlog.md`. Then refresh
the root cross-package aggregate (see step 5) so the closed story stops
showing up there.

## What this skill reads and writes

**Reads:**
- The target story file's frontmatter (`id`, `status`, `epic`, `depends_on`,
  `roadmap_ref`) and the project's `story.status` vocabulary.
- The scope's `{{DOCS_DIR}}/queue.md` and `{{DOCS_DIR}}/backlog.md`.
- The parent epic file when `epic:` is set and the epics extension is active.

**Writes (Agent mode only):**
- The story file — `status` only (and `updated`).
- `{{DOCS_DIR}}/backlog.md` — the matching **Status** cell.
- `{{DOCS_DIR}}/queue.md` — remove the closed row, renumber.
- The parent epic file — via the `close.epic-update` injection (see below).

## Mode: propose vs apply

Same contract as `doccraft-queue-audit`, set by the environment, not by user
enthusiasm:

- **Apply (Agent mode).** The tool can write files — perform the transition
  and reconcile in the same turn, then report what changed.
- **Propose (Ask / read-only mode).** The tool cannot write files — emit the
  exact diff you *would* apply (which files, which cells, which rows) and
  stop. NEVER write in Ask mode even if asked; the user applies it themselves.

## The close transaction

Run these in order. If any step cannot be completed unambiguously, stop and
report (see **Stop and report**) rather than leaving a partial close.

1. **Resolve the target.** Locate exactly one story file matching the id /
   namespaced id / active file. If zero or more than one match, stop and ask —
   never guess which story to close.

2. **Pick the terminal status.** Use the status the user named; default to
   `done`. It MUST be one of the project's `story.status` terminal values.
   Set the story's `status` and bump `updated` to today. Do not touch other
   frontmatter.

3. **Backlog Status cell.** In the scope's `{{DOCS_DIR}}/backlog.md`, find the
   row for this story (by `roadmap_ref` / id) and set its **Status** cell to
   the project's established "closed" phrasing for that terminal state. NEVER
   mark a backlog row closed when the story file is still `todo` /
   `in_progress` — the backlog follows the story, never leads it.

4. **Queue row.** In the scope's `{{DOCS_DIR}}/queue.md`, remove the closed
   story's row from the *Suggested order* table and renumber the rows below
   it. A closed story never stays in the pick-next list.

5. **Epic update (injection).** If the project uses epics, run the
   `close.epic-update` fragment below — mark the story's row in the parent
   epic's table and roll the epic to a terminal status when its last open
   child closes. Absent the extension this is a no-op.

<!-- doccraft:inject point=close.epic-update -->
<!-- /doccraft:inject -->

6. **Reconcile.** Run the `doccraft-queue-audit` invariants over the affected
   scope (graph checks, queue-order checks, backlog-drift checks) so closing
   this story did not strand a dependent or leave a stale row elsewhere. In a
   monorepo, also regenerate the root cross-package aggregate so the closed
   story is dropped from it. Do not restate the audit rules here — apply the
   same ones `doccraft-queue-audit` defines, so the two skills can never
   reconcile a queue differently.

## Stop and report (no edit)

NEVER guess through these — report and let the user decide:

- **Ambiguous target.** The id / phrase matches zero or several stories.
- **Unknown terminal status.** The requested status is not a terminal value
  in `story.status`. List the valid terminal values.
- **Dependent would be stranded.** Closing this story leaves a dependent whose
  only path forward was this story and whose other prerequisites are
  unfinished — surface it; the close is still valid, but the user should see
  the downstream impact.
- **Working-tree conflict.** Uncommitted changes exist in a file you would
  write. Report the plan; never overwrite in-progress work.

<!-- doccraft:inject point=close.instructions -->
<!-- /doccraft:inject -->

## Pre-apply validation

Before writing anything in Agent mode, MUST complete these checks:

1. **Single target resolved** — exactly one story file matches; scope is
   determined. If not, stop and ask.
2. **Terminal status valid** — the chosen status is in the project's
   `story.status` terminal set.
3. **Backlog row located** — the story's backlog row is found before editing
   its Status cell; if no row exists, note it rather than inventing one.
4. **Queue row located** — the queue row is found (or confirmed absent) before
   renumbering.
5. **Working-tree clean** — for every file to be written; otherwise report and
   defer to the user.

## Invalid examples (do not use)

- Flipping the story `status` and stopping — leaves the backlog, queue, and
  epic stale. The whole point of this skill is the full transition.
- Marking a backlog row or epic row closed while the story file is still
  `todo` / `in_progress` — status flows story → backlog/epic, never the
  reverse.
- Inventing a terminal status not in `story.status` — extend the vocabulary in
  `doccraft.json` first (via `doccraft-config`).
- Deleting a `depends_on` edge on a dependent to "unblock" it after a close —
  never; surface the stranded dependent and let the user decide.
- Writing files in Ask / read-only mode — emit the diff only.
- Creating a commit unless the user asks.

## Done condition

The task is complete when:

- Exactly one story's `status` is set to the intended terminal value and
  `updated` is bumped.
- The matching `{{DOCS_DIR}}/backlog.md` Status cell reflects the closure.
- The story's `{{DOCS_DIR}}/queue.md` row is removed and rows renumbered.
- If the project uses epics: the parent epic table reflects the closed story
  (via `close.epic-update`).
- The `doccraft-queue-audit` reconcile has run over the affected scope (and
  the root aggregate refreshed in a monorepo) with no unreported drift.
- Nothing was written in Ask / read-only mode.

## References

- `doccraft-queue-audit` — the reconcile invariants this skill defers to.
- `doccraft-story` — the frontmatter contract and terminal `status` vocab.
- `{{DOCS_DIR}}/queue.md`, `{{DOCS_DIR}}/backlog.md` — the surfaces reconciled.

> Project-specific vocabulary (terminal `status` values, queue-table headings,
> docs dir) lives in `doccraft.json` — the **Configuration** section lists the
> keys this skill reads. The defaults in this body apply when no config is
> present.