Doccraft Story

doccraft — planning stories

When to use

• Creating a new story in {{DOCS_DIR}}/stories/.
• Updating status, acceptance criteria, tags, or openspec on an existing story.
• When closing a story: update {{DOCS_DIR}}/queue.md and the Status column in {{DOCS_DIR}}/backlog.md. See Workflow reminders for queue-audit invocation rules.

YAML frontmatter (required fields)

Use valid YAML between --- delimiters at the top of the file. Every field marked yes MUST be present — do not omit any. If the user has not provided enough information to fill a required field, ask — NEVER guess.

Do not invent new values for status, impact, or urgency without first adding them to the matching story.* enum in doccraft.json — those are the single source of truth. For openspec, update this skill in the same change. One-off nuance belongs in the body, not as a new enum value.

openspec guidance

• not-needed — small change, obvious scope, few files.
• recommended — multi-module, schema/graph shifts, ambiguous scope, or high regression risk; add a sentence in the body: OpenSpec recommended because: …
• required — project policy demands formal spec-before-code for this class of change.

Do not create an openspec/ tree unless the repository has adopted OpenSpec; the field is preparatory.

File location and naming

• Path: {{DOCS_DIR}}/stories/<slug>.md — kebab-case slug.
• P-tier stories (aligned with a prioritised backlog): use p{tier}-<topic>.md where tier is p0…p4. The ordinal (e.g. P0.3) lives in YAML id, not in the filename. Examples: p0-payment-retry-flow.md, p2-observability-rollout.md.
• Non-tier work: stable prefix + slug, e.g. opt-2a-workflow-rename.md.
• One story per file. No epic folders — use prefixed tags for grouping.

Body template

After frontmatter, use these markdown sections in this order:

1. Problem / outcome (required) — what user or system need this addresses.
2. Acceptance criteria (required) — bullet list, testable where possible.
3. Notes (optional) — links to code (src/...), related ADRs, PRs.

Do not add other top-level sections. Put additional context in Notes.

Example

---
id: P0.3
title: Payment retry flow with idempotency keys
status: todo
impact: H
urgency: now
tags:
  - area:api
  - area:data
openspec: recommended
updated: 2026-04-18
roadmap_ref: P0.3
depends_on: []
adr_refs:
  - 003-payment-gateway-choice.md
---

## Problem / outcome

Failed third-party charges silently drop transactions; add retries with
idempotency so users can reorder without double-billing.

## Acceptance criteria

- [ ] Retries use persisted idempotency keys.
- [ ] Integration tests cover success, transient-failure, and permanent-failure paths.
- [ ] Runbook updated with the new retry behaviour.

## Notes

OpenSpec recommended because: touches schema + payment service + integration tests.

Tag vocabulary

Every tag MUST use a prefix so subsystem vs product slice vs cross-cutting theme is unambiguous. Use lowercase after the colon (e.g. area:api).

A story may list several tags, e.g. area:api, area:data, theme:performance.

Extending the vocabulary

• If no existing area:, slice:, or theme: value fits, and the label will recur, add it to the matching list in doccraft.yaml (keys story.areas / story.slices / story.themes). Commit the config edit together with the first story that uses the new value.
• One-off nuance that will not recur belongs in the body (Notes), not as a new tag.

Do not edit the tables in this SKILL.md directly — doccraft update regenerates this file and would overwrite the edit. doccraft.yaml is the single source of truth for project-specific vocabulary.

Invalid examples (do not use)

• Bare words: api, ui — always use a prefix so the kind of label is explicit.
• Wrong prefix for the kind of label (e.g. area:ui while slice:ui is the convention) — prefer slice: for product surfaces.

Pre-write validation

Before writing or updating a story file, MUST complete these checks:

1. Unique id — scan all {{DOCS_DIR}}/stories/*.md frontmatter and confirm the id value does not already exist. If it does, stop and ask the user for a different id.
2. Valid depends_on — every entry in depends_on MUST match an existing story's id value. If a reference is not found, stop and ask the user to clarify.
3. Valid tags — every tag MUST use a recognised prefix (area:, slice:, theme:). Bare words are NEVER acceptable.
4. Valid enums — status, impact, urgency, and openspec values MUST match the allowed values (from doccraft.yaml or the defaults in the frontmatter table above).
5. Required fields present — all fields marked "yes" in the frontmatter table MUST be present. If the user has not provided enough information to fill impact, urgency, or openspec, ask — do not guess.

Done condition

The task is complete when:

• The story file exists at the correct path ({{DOCS_DIR}}/stories/<slug>.md).
• Frontmatter contains all required fields with valid values.
• Body contains at minimum Problem / outcome and Acceptance criteria.
• If depends_on was added or changed, doccraft-queue-audit has been invoked in the same turn.
• If the story was closed (status: done), {{DOCS_DIR}}/queue.md and {{DOCS_DIR}}/backlog.md have been updated.

Configuration

Read doccraft.yaml at invocation. The story: section is this skill's customisation surface; override the defaults in the tables above with the values found there. If the file is missing or the story: section is absent, use the defaults as-is.

Relevant keys:

• docsDir — root folder for all docs, relative to project root. Default: docs. Stories live at {docsDir}/stories/.
• story.areas, story.slices, story.themes — tag vocabulary lists (replace the default area: / slice: / theme: values).
• story.status — allowed values for the status: field. Default: [todo, in_progress, done]. Extend if your project uses additional states (e.g. blocked, abandoned).
• story.urgency — allowed values for the urgency: field. Default: [now, soon, later]. Some projects use tier names (p0..p4) directly here, or mix both.
• story.impact — allowed values for the impact: field. Default: [H, M, L]. Override for projects that prefer [high, medium, low] or another taxonomy.
• story.id.tiers — filename tier prefixes like p0…p4. Empty list [] means the project does not use tier prefixes.
• story.id.pattern — regex accepting valid story id: values in frontmatter. Use this to validate new stories and to normalise depends_on typos. Default: ^(P\d+(\.\d+)?|[a-z][a-z0-9-]+)$.

Adding to a list in doccraft.yaml teaches the skill a new valid value without touching this file (which doccraft update regenerates). That is the intended way to extend vocabulary for a project.

Package context

For monorepo projects, stories may live at the project root or under a declared package's {{DOCS_DIR}}/stories/ tree (a Known package roots block appears above when packages are declared). For single-root projects no block appears, every story lives at the project-root {{DOCS_DIR}}/stories/, and the namespace rules below do not apply.

When the project declares packages, decide which scope to write to:

• Explicit package: arg. If the user names a package (e.g. "create a story for audio-engine"), write to that package's {{DOCS_DIR}}/stories/ and use the namespaced id form <slug>/STR-NNNN.
• Active-file inference. If the user is editing a file under a declared package path, default to that package's docs root.
• Root default. Otherwise, write to the project-root {{DOCS_DIR}}/stories/ with an unprefixed id.

In depends_on, the form <slug>/STR-NNNN references a story under that package's {{DOCS_DIR}}/stories/; unprefixed ids always refer to the project-root scope. The same namespace rule applies to adr_refs (unprefixed = root, <slug>/NNN-slug.md = package-scoped).

Cross-reference resolution (path-bearing links)

Per ADR 017, a cross-reference should resolve in one hop — opening the target should never require globbing a directory to find the file. The namespaced id stays the canonical, rename-stable handle; pair it with a path so neither readers nor agents pay a search tax:

• In frontmatter lists (depends_on, adr_refs), keep the id form — link syntax in a YAML list is awkward, and the audit resolves these against the Known package roots anyway. Ids remain canonical here.
• In prose, tables, and Notes — whenever you write a reference a reader or agent will follow (a related-story line, a queue row, an epic table), render it as a markdown link whose text is the id and whose target is the resolvable file path: [pipeline/P1.30](../services/pipeline/{{DOCS_DIR}}/stories/p1-...md).
• The id is the source of truth; the path is a convenience that the audit (doccraft-queue-audit) re-derives from the id and repairs when a file moves — so a stale path is a mechanical fix, not a dead link.

Workflow reminders

• Move status to in_progress when you start implementation; done when shipped or explicitly abandoned (note why in body if abandoned).
• After creating a story or changing depends_on, invoke doccraft-queue-audit in the same turn so the working queue stays consistent with the dependency graph.
• When closing a story (status: done), update {{DOCS_DIR}}/queue.md and the Status column in {{DOCS_DIR}}/backlog.md in the same commit.