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.

Field	Required	Values / notes
id	yes	Stable, unique id across all stories. P0.3 when aligned to {{DOCS_DIR}}/backlog.md, or a slug like story-2026-001. MUST be unique — verify before writing.
title	yes	Short human-readable title.
status	yes	One of the values in story.status config (default: todo | in_progress | done). Manual updates only.
impact	yes	One of the values in story.impact config (default: H | M | L). If the user does not specify, ask.
urgency	yes	One of the values in story.urgency config (default: now | soon | later). If the user does not specify, ask.
tags	yes	YAML list of prefixed strings (area:, slice:, theme:) from the tag vocabulary below. If nothing fits and the label will recur, extend the vocabulary in doccraft.yaml in the same change.
openspec	yes	MUST be set to one of: not-needed | recommended | required. See openspec guidance below.
updated	yes	ISO date YYYY-MM-DD. MUST be set on creation and updated on every meaningful edit.
roadmap_ref	optional	e.g. P1.7 — pointer to the backlog row when applicable.
depends_on	optional	YAML list of story id values that MUST be satisfied before this story is picked up (prerequisites). Omit or [] if none. Each entry MUST match another story's id or a backlog id you intentionally treat as external — prefer real story ids so the queue-audit graph stays honest.
adr_refs	optional	List of ADR filenames this story implements or contradicts (e.g. 001-foo.md).
openspec_change	optional	Path or name of the OpenSpec change folder when one exists.

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.

<!-- doccraft:inject point=story.frontmatter.fields --> <!-- /doccraft:inject -->

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.

<!-- doccraft:inject point=story.body.sections --> <!-- /doccraft:inject -->

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).

Prefix	Meaning	Examples
area:	Subsystem / code area. Align with your project's commit scopes where you already have them.	area:api, area:cli, area:auth, area:data, area:infra, area:schemas
slice:	Product surface that spans multiple areas.	slice:ui, slice:admin, slice:onboarding
theme:	Cross-cutting quality or kind of work.	theme:observability, theme:performance, theme:security, theme:docs, theme:testing

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

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

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.

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