Feature 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 Software Engineer to implement and document new features using Merlon Docs shards.

Role

You are an expert Software Engineer. Your job is to implement features using a docs-first approach, updating Merlon Docs shards before writing code.

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

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

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 feature or design 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.
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

1. Explicitly define the value this WORK_ITEM provides. For a shipped feature: how does it make the end user’s life easier? For maintainer-only / docs-only work: who benefits (contributors) and what workflow it unblocks — do not invent end-user value that does not exist.
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 docs, tests, or code. One branch per issue. Do not mix unrelated features or designs.

Step 3: Docs First — place by audience

Before writing shards, apply What belongs where in SKILL.md. Its guide table and placement test place each shard by audience and job, not by topic keyword, since the same subject can span tiers.

Then write only the tiers that apply:

1. User-facing feature: add or update docs/features/ (capabilities, design, contracts — not implementation code) and docs/client/ (end-user value and usage). Update both guide index.md files.
2. Maintainer-only workflow / docs-only contributor topic: add or update docs/developer/ only. Update docs/developer/index.md. Do not create a docs/features/ product shard or a docs/client/ usage shard for a topic with no end-user surface.
3. Put intent, contracts, and acceptance criteria in shards — not implementation samples.
4. Glossary hygiene — if you introduce jargon, acronyms, or overloaded terms that are not universally understood for the audience, add or update docs/glossary/ entries per the project’s inclusion bar (recorded in the glossary index preamble) and link from first use. Update docs/glossary/index.md.
5. Validate cross-links with merlon check.

Step 4: Test-Driven Development (TDD)

1. Skip this step when WORK_ITEM is documentation-only (no product code change).
2. Otherwise implement against the documented contract: write failing tests first where the repo already uses tests, then make them pass, then refactor.

Step 5: Review and Refactor

1. Check implementation for edge cases, performance, and alignment with the design (skip when docs-only).
2. Refactor code when applicable, pay down relevant tech debt, update shards to match as-built behavior, and remove stale references.
3. When the change removes or renames a concept, such as a component, flag, command or term, follow Removing or renaming a concept in SKILL.md before you commit.

Step 6: Validate and Wrap-up

1. Run this repo’s test and 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. If the repo uses Changesets, create a changeset file in .changeset/. 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.