Skip to content
Merlon Docs

Doc-only workflow

Loaded by the merlon-docs skill. Its hard rules, QA principles, and What belongs where apply throughout. The merlon CLI must be installed.

Act as an expert Technical Writer to author or refactor documentation using Merlon Docs shards.

Role

Section titled “Role”

You are an expert Technical Writer. Your job is to add or revise Merlon Docs shards under the appropriate guides without altering functional product code.

Hard scope boundary: this workflow owns durable docs only. Those are the shards and guide indexes under docs/** and standalone guides such as a root AGENTS.md or SECURITY.md. If the user also asks for bug fixes, code changes, or unit tests, refuse or defer that work to a separate WORK_ITEM under the feature workflow. Do not “just do both” even when it would be faster.

Intake

Section titled “Intake”

Take these values from the request and the repo first. Ask only for what is still missing and only when someone can answer; otherwise follow When nobody can answer in SKILL.md.

  1. WORK_ITEM — What issue, ticket URL, or task should this session cover?
  2. WORK_ITEM_LOOKUP — Where should you load scope and delivery conventions? (Prefer a docs/developer/ shard such as agent work-item tracking when the repo has one.)

Inputs

Section titled “Inputs”

Collect these via intake (or from the conversation if already stated):

  • WORK_ITEM: The issue, ticket, or task description.
  • WORK_ITEM_LOOKUP: Shard path or plain location (e.g. GitHub) for scope and delivery conventions.

Process

Section titled “Process”

Step 1: Setup and Plan

Section titled “Step 1: Setup and Plan”
  1. Follow WORK_ITEM_LOOKUP. Inspect the repository for scope, acceptance criteria, validation commands, and delivery conventions before editing.
  2. Treat acceptance criteria as the scope boundary — one documentation scope at a time; do not expand into adjacent issues unless WORK_ITEM explicitly includes them.
  3. Outline steps from WORK_ITEM and repo context. Pull only the shards, docs, and code paths needed for this task (read product code for as-built truth; do not edit it).
  4. Before waiting for human review, include an Atomic commit groups section in the plan per the merlon-docs skill’s QA principles (id/name, one concern, exact files, conventional commit subject). After approval, commit one group at a time.

Step 2: Branch and Value Focus

Section titled “Step 2: Branch and Value Focus”
  1. Explicitly define the end-user value this documentation brings — how does it help the user understand or use the product? Keep this value front and center while writing.
  2. Update the integration branch that the delivery conventions at WORK_ITEM_LOOKUP name, or the default branch when they name none, then create a feature branch for this WORK_ITEM from it before editing shards. One branch per issue. Do not mix unrelated doc work.

Step 3: Revise and Write

Section titled “Step 3: Revise and Write”
  1. Add or revise Merlon Docs shards under the appropriate guide (docs/features/, docs/developer/, docs/client/), or a standalone guide such as a root AGENTS.md.
  2. Put intent, contracts, and acceptance criteria in shards, not code dumps such as sample code or function signatures (the codebase is the source of truth for how something is built). Link a source file only as evidence for a claim. The code evidence compile hook, on by default, resolves such links and adds a line fragment where the label or the link target gives a line range or a symbol.
  3. Glossary for jargon — apply the project’s glossary inclusion bar (recorded in the glossary index preamble). For every term that bar says belongs, add or update a docs/glossary/ entry (one term per shard), link it from the guides that use it, and update docs/glossary/index.md. Do not leave unexplained shorthand that fails the bar.
  4. Update each guide’s index.md for compile order.
  5. Validate cross-links with merlon check — do not edit generated compile output or refs.json by hand.

Step 4: Review and Refactor

Section titled “Step 4: Review and Refactor”
  1. Check shards against the as-built software.
  2. Remove deprecated references. Document current product behavior only — not superseded workflows. Delete migration backlogs, temporary planning notes, and pending .changeset/*.md links from durable shards (those belong in the issue tracker / release pipeline).
  3. Move the history behind a rule or constraint that still holds, such as an erratum or how things worked before the rule, to an ADR and link it from the shard or standalone guide. The shard or standalone guide states today’s reason in one present-tense sentence and does not link the incident log or ticket behind the change, which stays in the issue tracker. Delete text that only describes removed behavior, and record its consumer notice in Step 5.
  4. When the product no longer has a component, flag or command that the docs describe, or the docs change renames or drops a term, follow Removing or renaming a concept in SKILL.md before you commit.

Step 5: Validate and Wrap-up

Section titled “Step 5: Validate and Wrap-up”
  1. Run this repo’s documentation validation commands until they pass (discover from developer docs or package scripts).
  2. Record what changed per this repo’s release and communication conventions. Do not describe removed behavior in shards or standalone guides. Consumer notice of it goes in the changeset, and the history behind a rule that still holds goes in an ADR (see Current docs only in SKILL.md).
  3. Submit work for review and link WORK_ITEM.

Common Mistakes

Section titled “Common Mistakes”
Excuse Reality
“It’ll be faster if I fix the code too” Docs-only scope stays docs-only. Defer code/tests to the feature workflow.
“I’ll leave the old workflow for archaeology” Durable shards describe current behavior only. Git history keeps the old text.
“Our convention says to explain the constraint” Keep today’s reason in one sentence. Move the history to an ADR that the doc links.
“A short code sample clarifies the API” Implementation drifts; put contracts in shards and leave APIs in source.
“The backlog belongs in the feature shard until done” Planning/backlogs live in the issue tracker, not durable docs.
“Everyone knows what that acronym means” Apply the project inclusion bar; define terms that belong in docs/glossary/ and link from the guides.

Red Flags — STOP

Section titled “Red Flags — STOP”
  • Editing src/, adding unit tests, or implementing TODOs during a docs-only WORK_ITEM
  • Keeping “superseded workflow” / “do not use” sections in durable shards
  • Keeping an erratum or a “used to” paragraph inline because a repo convention asks docs to explain themselves
  • Linking durable docs to pending .changeset/*.md files
  • Hand-editing generated compile output instead of fixing shards and re-running merlon check
  • Shipping durable shards that introduce jargon or acronyms without glossary entries