Skill workflows

Normative profile for the workflows inside the Merlon Docs Agent Skill that drive shard authoring across the four guide tiers. Parent spec: Merlon Docs 1.0.

Purpose

Workflows are part of the Merlon Docs authoring process — not host-specific rules. They tell agents how to load a WORK_ITEM, which guides to write, and how to validate before merge. People install one skill (merlon-docs) and invoke it as /merlon-docs with the task in plain words; the skill picks the workflow from its routing table and loads only that workflow’s file.

Workflow files live in the skill under skills/merlon-docs/references/workflows/ (e.g., feature-level.md). The canonical catalog is summarized below. Do not edit an installed copy of the skill if you want changes to persist — propose upstream or add extensions.

The obligations on this page are advisory, as Enforceable rules uses the word, and that page lists the partial gates some of them have. The agent following the skill applies them. Its plan and the branch’s commits are the evidence a session leaves, and the optional live skill evals measure the skill against them outside CI.

Required intake

Every work-item workflow MUST open with an Intake section listing the fields below. The agent takes each value from the request and the repository first, and asks only for what is still missing when someone can answer. When nobody can answer, as in a headless or scheduled run, it states a default in one line and continues. WORK_ITEM is then the request itself. It stops to wait only when the user asked for a plan first, or before a destructive or irreversible step, a real change of scope, or input only the user can give. The skill’s When nobody can answer section in SKILL.md holds these defaults.

The live eval runs behind the headless behavior are in the research record Skill eval round: measured changes to the Merlon Docs skill. A later round, Skill eval round: harm check after aligning the skill with its docs, ran a harm check on the wording aligned with this page and the other docs it repeats. The one difference it found is inside run-to-run noise.

Required fields for work-item workflows:

Field	Meaning	Example intake question
WORK_ITEM	Enough to resolve the task: tracker id, URL, or short issue name/description	What issue, ticket URL, or task should this session cover?
WORK_ITEM_LOOKUP	Where to load scope and delivery conventions: a shard path or a plain location, such as the issue tracker	Where should you load scope and delivery conventions? (Prefer a docs/developer/ shard.)

The getting-started workflow MUST collect FEATURE, PERSONA, and EXPERIENCE (novice vs expert onboarding depth) instead of WORK_ITEM. EXPERIENCE defaults to expert when nobody can answer. After a successful bootstrap, it MUST offer an optional first-feature tutorial (RUN_FIRST_FEATURE_TUTORIAL, default yes for novice) and, when accepted, resolve EXAMPLE_MODE (recommended hello-greeting or bring-your-own) before walking design → feature → UX → doc-only. Detail: Getting-started workflow.

The doc-review workflow collects SCOPE and WORK_ITEM_LOOKUP instead of WORK_ITEM.

Agents MUST load the issue (or equivalent) before editing shards or code. One WORK_ITEM per branch. The branch starts from the integration branch that the delivery conventions at WORK_ITEM_LOOKUP name, or from the default branch when they name none.

Atomic commit groups (plan obligation)

A coding or multi-concern plan from a day-to-day workflow (feature-level, doc-only, design-architecture, UX or doc-review) MUST include an Atomic commit groups section before waiting for human review / “go”. Doc-review plans its groups in Step 4, the other four in Step 1. Each numbered group lists id/name, one concern, exact files, and an intended conventional commit subject. After approval, work through the groups one at a time and git commit each one. Don’t squash unrelated concerns into one commit.

Why: reviewable diffs, one concern per commit, and it matches small batches (the skill’s QA Principles).

Bootstrap scaffold (getting-started steps 1 to 6) stays out of scope for commit grouping. When the optional first-feature tutorial runs, each phase follows the matching day-to-day workflow, commit groups included.

Standard workflows

Workflow	Role	Primary guides
getting-started	Bootstrap + first-feature tutorial	all tiers
feature-level	Feature engineering	features/, client/, code + tests
doc-only	Technical writing	features/, client/, developer/, standalone guides
design-architecture	Architecture as Merlon Docs shards	features/, features/adr/
ux	User-centric journeys	client/, glossary
doc-review	Whole-set review: merge, split, move, reword	any guide and its index

Goals and hard boundaries for each workflow (what it is / is not):

• Getting-started workflow
• Feature-level workflow
• Doc-only workflow
• Design-architecture workflow
• UX workflow
• Doc-review workflow

Index: skills.md. Each workflow also has an optional live skill eval suite under tests/skills/merlon-docs/evals/.

Guide placement obligations

Every workflow MUST apply the placement test in Default guide layout to each shard it writes. The Primary guides column in Standard workflows shows which guides each workflow writes. A fix for a removed or renamed concept can reach any guide or standalone guide from every workflow, as the concept removal obligation requires.

Glossary obligation (every workflow)

Every workflow MUST treat glossary hygiene as part of its session — not an optional afterthought for doc-only or UX alone.

• Non-universal language — If a shard introduces jargon, acronyms, or overloaded terms that are not universally understood by the guide’s audience, define them under docs/glossary/ (one term per shard) and link from first use.
• Project inclusion bar — What does / does not belong in the glossary is a judgment call. The project’s bar is recorded in the glossary itself (typically the docs/glossary/index.md preamble). Workflows MUST follow that bar; when none exists yet, getting-started establishes it with the end user.
• Not a dump of everyday words — Do not glossary terms that are already unambiguous for the stated audience; prefer a short entry over unexplained shorthand when the bar is unclear.

Shared glossary covers how guides share the glossary’s term shards.

Concept removal obligation

A workflow whose change removes or renames a component, flag or command in the product, or a term in the docs, MUST follow the skill’s Removing or renaming a concept steps before it commits. So MUST a workflow whose change, such as an ADR written after the removal, finds docs that still describe a component, flag or command that the product no longer has. Docs describe a concept for as long as the product has it, so a design that only plans a removal leaves them unchanged, and the change that makes the removal runs the steps. The search starts at the repository root, so it reaches a standalone guide outside the docs root as well as the shards. The change fixes each hit in a durable doc that refers to the old concept, whatever the workflow’s own scope, and its commit message gives each search command and the files it hit. Historical records such as ADRs, CHANGELOGs and research records keep their mentions, and so do pending release notes. The change leaves a hit in a vendor-managed skill install or a test fixture as it is, because neither is a durable doc of the repo.

Entrypoint chain

/merlon-docs <feature request> → feature-level workflow → intake questions → shards → merlon check
/merlon-docs <design request>  → design-architecture workflow → intake → feature/ADR shards → merlon check
/merlon-docs review the docs   → doc-review workflow → merlon review → decisions → shards → merlon check

The chosen workflow collects WORK_ITEM_LOOKUP via intake for scope.