Writer workflow
This contract owns the writer’s editorial boundaries, file mechanics, iteration behaviour, and PM handoff. The selected authoring skill owns the page-specific content method. The Iterate mode owns orchestration, validation, review, and finalisation. The shared output layout owns generated paths.
Call types
| Brief | Action |
|---|---|
| Draft, iteration 1 | Audit the supplied source or brief, then create the first iteration draft. Create a preservation ledger only for an existing source page. |
| Revision, iteration 2 or later | Revise the best draft into a new iteration file. |
| Corrective fix | Fix the PM’s exact mechanical errors in the existing iteration file. Do not start a new iteration. |
There is no finalise brief. The PM copies the selected draft without an LLM rewrite.
Editorial invariants
Apply these invariants to every draft:
- Maersk usage focus. Explain how and when to use the subject in Maersk logistics and shipping. Do not write a generic explainer.
- No implementation prose. Do not add API reference or technical implementation content. Use a supplied API surface only to fact-check a claim.
- Preserve decisions. Keep every verified source rule and decision. Do not import unverified
content. Apply the preservation-ledger rules below when the source state is
existing. An existing MDS rule, example, image or placement is an MDS decision, not an external claim: keep it and flag it when external research disagrees or says nothing. Drop it only for MDS evidence (foundations, verified component behaviour, an owner decision in the brief), and never because research found no support for guidance about an MDS component or composition. - Accessibility scope. Cover author responsibilities such as label text, composition tab order, and custom-content contrast. Use at most one line to acknowledge verified built-in ARIA, keyboard, or focus behaviour. Do not enumerate built-in behaviour. When the author has no responsibility to state, omit the Accessibility section: a heading over one line about built-in behaviour tells the reader nothing to act on.
- External additions are proposals. Guidance found only in external research is not page content. Return it in the handoff as a proposal (the idea, its sources, the suggested placement) for the human to accept, and keep it out of the draft until a brief approves it.
Writer procedure
- Read the brief and this contract.
- Apply the matching branch below.
- Return the writer handoff.
| Brief | Procedure |
|---|---|
| Draft or revision | Read the selected authoring skill and its routed references. Apply the iteration rules. Write only to the assigned path. Update the preservation ledger when the source state is existing. Run Draft and Self-check, then complete the content voice-and-tone process. |
| Corrective fix | Change only what is needed to fix the PM’s exact mechanical errors in the existing iteration file. |
Do not fetch external sources. Use the research brief and workspace only. Treat a claim marked
contested in the research brief as unverified: do not state it as fact. This governs new claims.
An existing source rule that is contested stays in the draft in its source wording and is flagged
in the handoff (invariant 3).
Do not read a content-quality ledger or previous review except the findings in the brief.
Do not review or rate the draft.
Iteration rules
| Iteration | Audit | Draft source | Component API check |
|---|---|---|---|
| 1 | Run the authoring skill’s Audit section. | Existing source page or approved new-page brief. | Sense-check the full supplied surface. |
| 2 or later | Skip Audit. | Best draft named in the brief. | Check only claims challenged by reviewer findings. |
For an existing page, map the live page to the selected template during Audit.
Run Draft and Self-check on every iteration. Apply the content voice-and-tone skill once after Self-check.
A revision brief includes each best-draft reviewer finding and its ID.
When a later attempt was not selected as the best draft, the brief also includes its findings
labelled from a non-selected attempt.
Never overwrite an earlier iteration draft or the live page.
The PM finalises the selected draft at
ak-<document-key>-best-draft/<source-filename>.
A human promotes that draft later.
Draft paths
| Draft location | Component and image references |
|---|---|
Working draft (in the cache, written as if at _ak/<document-key>/drafts/) | ../../../_components/... and ../../../_images/... |
ak-<document-key>-best-draft/ | ../_components/... and ../_images/... |
Do not use ./_components/... or ./_images/... in either location.
Drafts derived from an existing page MUST include navTitle: Authoring Kit Draft in frontmatter.
Every <PageLink> target MUST exist in .cache/pages.json.
If the intended target is absent, use the nearest valid page or leave the text unlinked.
Record that choice in the handoff.
Images
| Image case | Draft value |
|---|---|
| New example | imageSrc="./image-required.svg" |
| Existing approved image | Keep the real relative _images path. An image is source content: drop it only with a ledger reason that meets invariant 3, not because the rule beside it was reworded. |
A new page has no approved images, so every example uses the placeholder. Use placeholders only for genuinely new images.
Write each placeholder’s aiCaption Setup: clause as a complete commissioning brief.
List every placeholder in the handoff’s proposed-assets note.
Preservation ledger
The preservation ledger applies only when the source state is existing.
| Source state and iteration | Ledger action |
|---|---|
existing, iteration 1 | Create preservation-ledger.md in the cache drafts/ folder (the path the PM gives) with one row per verified source decision. |
existing, iteration 2 or later | Update affected rows. Do not delete or regenerate earlier history. |
new, any iteration | Do not create a preservation ledger. Preserve verified decisions through the approved brief, research evidence, and immutable draft history. |
For an existing page, record each decision as kept, rephrased, moved, or dropped-with-reason. If a later revision restores dropped content, add a restoration row instead of removing the drop. Only the writer creates or edits this file.
Keep a current state table at the top of the file: one row per source decision with its status in the latest draft, replaced in place on each iteration. The per-iteration tables below it stay as history. The reader of the ledger should not need the history to see what the draft keeps.
Component API surface
For a component page, the PM supplies componentApiSurface in every draft or revision brief.
It contains the installed component’s props, events, and slots from the package metadata api key.
The PM regenerates it for every brief.
Use the surface to check whether a proposed rule assumes a supported capability. Do not copy prop names, types, defaults, or descriptions into the draft.
If the surface is missing, treat every API-dependent claim as unverified. Disclose each affected claim in the handoff. Do not add or silently drop the claim.
Supporting implementation
The writer edits only the assigned MDX draft and, for an existing page, its preservation ledger. Do not edit demos, components, generators, images, live pages, or inbound source files.
Return required work as a proposal with its purpose, evidence, affected path, and suggested next step. Do not describe proposed behaviour as already implemented.
Mechanical corrections
The PM runs check-page-quality.mjs because the writer has no command-execution tool.
Fix every reported error in the same iteration file.
A corrective fix does not start a new iteration.
Treat notes as informational. Placeholder-image notes never block validation.
Pipeline metadata and proposals
Do not add ratings, model details, or other pipeline metadata to draft content. The PM reports that information under the Iterate final-report rules.
Keep an unsupported business example out of the draft. Return it as a proposal with its scenario, intended rule, evidence gap, and suggested placement.
Writer brief: PM to writer
The writer brief owns what the PM supplies. Treat its contents as your inputs.
Writer handoff: writer to PM
Return one message containing:
- iteration draft path, first;
- source content dropped or still contested, as a short list at the top with the reason for each, so owner decisions are not left in the ledger;
- external additions proposed for approval (see invariant 5);
- Self-check summary without a quality rating;
- preservation-ledger path and one-line change summary, or
—for a new page; - proposed assets for every placeholder image;
- supporting implementation proposals;
- proposed business examples;
- authoring-skill notes, including anchor changes or guideline extractions when applicable;
- open questions.