journeydoc-add-story

name	journeydoc-add-story
description	Append one tutorial story to a journeydoc-bootstrapped Conduction app — drops a markdown page + a capture-spec test block + sidebar entry, all in one PR. See ADR-030.
metadata	{"category":"Workflow","tags":["workflow","documentation","journeydoc"]}

Journeydoc Add Story — append one tutorial page

For an app that already ran /journeydoc-init, this skill adds one story to the user or admin track without touching the rest of the scaffold. Output: one new markdown page, one new test block in the capture spec, sidebar position auto-incremented.

Input: the slug + track + title.

• /journeydoc-add-story <slug> <track> "<title>"
• e.g. /journeydoc-add-story opencatalogi user "Search the catalogue"

If any of those is missing, ask via AskUserQuestion.

Reference: ADR-030: journeydoc.

---

Step 1: Resolve inputs

If the user only provided <slug>, ask:

"Which track does this story belong on? user / admin"

Then:

"Title for the story (one line, sentence case — e.g. 'Search the catalogue')"

Validate that the target app has been journeydoc-bootstrapped:

• {APP_DIR}/docs/tutorials/<track>/_category_.json exists
• {APP_DIR}/tests/e2e/docs-screenshots.spec.ts exists

If either is missing, abort with:

"App <slug> doesn't look journeydoc-bootstrapped yet. Run /journeydoc-init <slug> first."

Step 2: Compute filename + slug + position

Position: count the existing <position>-*.md files in {APP_DIR}/docs/tutorials/<track>/. The new story's position is that count + 1, zero-padded to 2 digits.

Slug: kebab-case the title. Strip articles (a, an, the) and common stop words. Truncate to ~30 chars.

Filename: <position>-<slug>.md.

Step 3: Ask 3 short questions to fill the template

Goal: in one sentence, what does the user accomplish?
Prerequisites: what must already be true? (one bullet per line, blank if none)
Steps: paste a numbered list of UI clicks. (you can leave step text rough — the
       capture spec drives them, the markdown is for human readers)

Use AskUserQuestion three times. Don't ask for verification + common issues — leave those as TODO comments in the generated page; the author fills them after the first capture run reveals real edge cases.

Step 4: Write the markdown page

Use templates/journeydoc/tutorial-page.md.template with placeholders resolved. Each numbered step in the user's input becomes:

### N. <step text>

![<short alt text>](/screenshots/tutorials/<track>/<position>-step-N.png)

The image path is the canonical journeydoc convention (/screenshots/tutorials/<track>/<file>.png). The PNG doesn't exist yet; Docusaurus will warn (not fail) on the missing image, and the author runs the capture spec to populate it.

Step 5: Append a test block to the capture spec

Open {APP_DIR}/tests/e2e/docs-screenshots.spec.ts. Find the relevant test.describe('docs: <track> track', () => { … }) block and append a new test() inside it:

test('<UN-or-AN> <slug> — REPLACE WITH ACTUAL FLOW', async ({ page }) => {
	// docs/tutorials/<track>/<position>-<slug>.md
	// Step 1: <step text>
	// await page.locator('[data-testid="…"]').click()
	await shoot(page, '<track>', '<position>-step-1.png')

	// Step 2: <step text>
	// …
	// await shoot(page, '<track>', '<position>-step-2.png')
})

Where <UN-or-AN> is U<position> for user track or A<position> for admin. The numbered TODO comments mirror the markdown so the author has 1:1 alignment when filling in selectors. Stable selectors via data-testid="…" — see journeydoc-instrument.

Step 6: Sidebar position is auto-correct

The numeric prefix in the filename drives Docusaurus's sidebar_position automatically. No _category_.json edits needed.

Step 7: Branch + commit + PR

cd {APP_DIR}
git checkout -b feature/journeydoc-add-<slug>
git add docs/tutorials/<track>/<position>-<slug>.md tests/e2e/docs-screenshots.spec.ts
git commit -m "docs(journeydoc): add user-story '<title>'"
git push -u origin feature/journeydoc-add-<slug>
gh pr create \
  --repo ConductionNL/<slug> \
  --base development \
  --head feature/journeydoc-add-<slug> \
  --title "docs(journeydoc): add <track>-track story '<title>'" \
  --body "<auto-generated body>"

Step 8: Print next-steps

✅ Story added: docs/tutorials/<track>/<position>-<slug>.md.

Next:
  1. Fill the per-step locators in tests/e2e/docs-screenshots.spec.ts.
     If you need data-testids, run `/journeydoc-instrument <vue-file>`.
  2. Run the capture spec to populate the screenshots:
       npx playwright test --project docs-capture --grep "<UN-or-AN>"
  3. Review the page in the dev server:
       cd docs && npx docusaurus start

PR: https://github.com/ConductionNL/<slug>/pull/<N>

---

Common patterns

• Story is admin-only — same flow with <track>=admin. The page goes under docs/tutorials/admin/.
• Story spans multiple steps with same screenshot — that's fine. Some steps are "do X then verify Y" and reuse the previous step's screenshot. Just don't add a shoot() call for steps that don't introduce a new visual.
• Story depends on another tutorial's state — reference it directly: [Create a record](02-create-record.md). Docusaurus resolves the filename to the prefix-stripped URL on render.