# Implement

> Work a batch of backlog items end-to-end as a maintainer — hold the Implementation Quality Bar, run the Pre-authoring stance check, log follow-ups on disk, flip items to `review-ready`, and ship one PR per repo per batch.

- Skill: `opendatadiscovery/implement` (Agent Skill)
- Install (CLI): `npx skillmds@latest add opendatadiscovery/implement`
- Raw SKILL.md: https://api.skillmd.com/api/skills/opendatadiscovery/implement/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: opendatadiscovery (https://skillmd.com/u/opendatadiscovery)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/opendatadiscovery/implement

---


# Implement a Batch

`$ARGUMENTS` is the **batch starter**, not the sole item. You are an ODD Team maintainer working a batch end-to-end: holding the Implementation Quality Bar, logging discovered follow-ups on disk, producing few cohesive PRs that the user can review in one pass.

If `$ARGUMENTS` is empty, show pending items sorted by priority and ask which to start the batch from.

**Release-gate form:** `/implement release:{version}` runs `playbooks/release-train-merge.md` **half 1** — pre-merge readiness for the documentation release train (milestone closed + release published + `tag_name == {version}`; final train sync; the step-6.5 mechanical sweeps over the full train diff; manifest completeness incl. the milestone-issue cross-check; push + the single train PR for the human to merge). Half 2 (post-merge live verification) belongs to `/review release:{version}`.

**You cannot self-mark items `done`.** This phase ends at `status: review-ready`. `/review` in a separate session handles the final transition. The lesson: `retrospectives/LSN-002-minio-region-unset.md` — self-closed items shipped a silent data-loss caveat that a separate-session review would have caught.

## What to load

Read in this order (the session-boot pattern from `CLAUDE.md`):

1. `CLAUDE.md` — universal framework, Quality Bar overview, batching rules.
2. `pillars/{active}/pillar.md` — the bar; for documentation-pillar items, `pillars/documentation/pillar.md` "The bar — stated explicitly".
3. `pillars/{active}/{cornerstones,gates,authoring,canonical-homes}.md` — pillar-specific rules.
4. `navigation/architecture.md` + `navigation/domains/{relevant}.md` — code pointers.
5. The work item file (search `backlog/`).

## Phase 1 — Plan the batch

1. **Pre-flight on the starter.** Status must be `pending`; check `state/file-registry.yaml` for conflicts; check `adrs/` for constraints; read every file in `affected_files`; consult navigation if a path is stale.

2. **Freshen `origin/main`** for every target repo the batch will touch. **Mandatory for `documentation`** (`retrospectives/LSN-008-stale-branch-false-positives.md`): fetch and checkout `origin/main` in `../documentation` before reading or editing. **Release-gated items** (`milestone:` in frontmatter — `adrs/drafts/release-train-doc-gating.md`): the documentation working branch is the **train** `release/{version}`, not a fresh batch branch — create it from freshly-fetched `origin/main` if absent (`git push -u origin release/{version}`); else check it out and **sync-first** (`git merge origin/main`; resolve; merge, never rebase). Leave `../documentation` checked out on `main` at session end.

3. **Assemble batch candidates.** From the backlog, pick continuation items that share the starter's `target_repo`, have no file conflicts with already-staged items, are small or medium effort, and share a theme (scanner source, feature area, or quality-bar concern). Name the batch after the theme it covers (e.g., `feature/docs-quality-xrefs`). Cut the batch branch from freshly-fetched `origin/main`; the odd-team bookkeeping lives on a parallel branch in this repo. **Routing class is a batch-compatibility dimension**: never mix release-gated (`milestone:` set) and immediate documentation items on one branch — for a release-gated batch the train branch IS the batch branch (per-item commits land on it directly; the only publication PR is the release gate's).

4. **Per-item: pre-authoring duplication sweep** → run `playbooks/duplication-sweep.md`. Existing-content + new-content + backlog-internal sweeps; record decisions in the item's Context. If the sweep shows the item is mis-scoped, drop it from the batch.

5. **Per-item: claim inventory + Sources plan** → run `playbooks/claim-inventory.md`. Draft the `Sources:` commit footer **before** authoring; name a verifiable SoT per claim class. If a claim's SoT is not reachable in <60s, drop the claim or mark the item `blocked` pending SoT.

## Phase 2 — Execute each item (in order on the batch branch)

Repeat per item.

1. **Flip status** — set the item's frontmatter to `status: in-progress`.

2. **Pre-authoring stance check** → run `playbooks/pre-authoring-stance.md` for **each sub-section** the change will introduce, not just at item start. Five questions: content type / canonical home / SUMMARY placement / WHY-preservation / Pride. If any answer reveals a structural mismatch, **stop and address the structural question first** — extend the canonical home, propose a new pillar, or escalate. Do not author over a known mismatch.

3. **SoT verification** → run `playbooks/consumer-read.md` (covers config / SDK / feature / error / spec / lifecycle / dep claim classes). For SDK-backed claims, this calls `playbooks/unset-parameter-audit.md` per builder. Every `caveat-defaulted` parameter is either documented in the change as a known limitation or logged as a new backlog item via `playbooks/follow-up-on-disk.md`.

4. **Author the change.** Hold every Quality Bar gate (universal cores in `playbooks/`; pillar specialisations in `pillars/{active}/gates.md`). Acceptance criteria are the floor; the gates are the bar.

5. **Follow-up auto-logging** → run `playbooks/follow-up-on-disk.md` for every out-of-scope discovery. Grep the backlog first; classify scope (trivial-fold / small-batch-item / larger-deferred / upstream-issue). Never write "noted as follow-up" without the file on disk.

6. **Pillar authoring rules** — for `target_repo: documentation`, hold `pillars/documentation/authoring.md` (no GitBook `"mention"` links; ship page + SUMMARY + index together; in-page TOC sync; `Sources:` footer format; **Gate 11 audience isolation** — the mechanical grep below; **release-gated content carries its version** — "Release-gated authoring": `Available since {version}`).

6.5. **Pre-commit mechanical sweeps** *(mandatory for `target_repo: documentation`)* — run BOTH checks on the staged diff before every documentation commit. **Do not commit if either check returns a hit.**

   **(a) Gate 11 audience-isolation grep** *(2026-05-27)* — banned-term sweep. Full rule + registry + exceptions in `pillars/documentation/gates.md` Gate 11. Case-law: `retrospectives/LSN-026`.
   ```bash
   git diff --staged --name-only -- '../documentation/docs' \
     | grep -E '\.md$' \
     | xargs -r grep -nE 'Cornerstone [0-9]+|Gate [0-9]+|\bLSN-[0-9]+\b|\bSHB-[0-9]+\b|\bREFACTOR-[0-9]+\b|\bTEST-GAP-[0-9]+\b|\bDOC-GAP-[0-9]+\b|\bADR-CANDIDATE-[0-9]+\b|feature-flow-builder|feature-reflector|doc-gap-finder|concept-merger|odd-sme|adr-archaeologist|methodology-reviewer|graph-retriever|file-analyser|probe-runner|domain-extractor|Stress Protocol|Quality Bar|Pre-authoring stance|claim-inventory|consumer-read|unset-parameter audit'
   ```
   For every hit: rewrite in operator language (name the underlying user-observable concept directly) OR delete (often the right call — internal references frequently signal the maintainer talking to themselves through the doc) OR move to an internal artefact. Re-grep until zero hits.

   **(b) Description-length check** *(2026-05-28)* — GitBook truncates the rendered `description:` frontmatter at exactly **200 chars** in four surfaces (`<meta name="description">`, `<meta property="og:description">`, `<meta name="twitter:description">`, AND the visible `<p>...</p></header>` page subtitle directly under the H1). Truncation is mid-word, no ellipsis, operator-visible on every page view. Full rule in `pillars/documentation/gates.md` Gate 8 + `playbooks/live-site-verification.md` step 3. Case-law: `retrospectives/LSN-027`.
   ```bash
   git diff --staged --name-only -- '../documentation/docs' \
     | grep -E '\.md$' \
     | while read f; do
         desc=$(head -3 "../documentation/$f" 2>/dev/null | grep '^description:' | head -1 | sed 's/^description: //')
         if [ -n "$desc" ]; then
           len=$(echo -n "$desc" | wc -c)
           if [ "$len" -gt 200 ]; then
             echo "OVER 200 ($len bytes): $f"
             echo "  → $desc"
           fi
         fi
       done
   ```
   For every hit: shorten the description before commit. Target ≤180 chars for a safety buffer. Preserve operator framing — name the load-bearing concept first; drop secondary clauses, abbreviate ("DB" for "database", "AWS SSM" for "AWS Systems Manager Parameter Store"); avoid trailing "instead of X" or "for Y" payoffs that consume the budget on a verbose framing the reader can absorb from the body's first paragraph. Re-check until the loop returns zero output. **Do not commit a doc change with any description over 200 chars.**

   **(c) YAML frontmatter parse check** *(2026-05-28; LSN-028)* — GitBook's import pipeline parses every page's YAML frontmatter with a strict parser. A `: ` (colon-space) inside a plain-scalar `description:` value reads as a nested mapping separator and stalls sync entirely (worse than truncation — the publisher freezes at the prior state until the hotfix lands). Full hazard catalogue + the PyYAML one-liner in `memory/reference_yaml_frontmatter_hazards_in_description.md`. Case-law: `retrospectives/LSN-028`.
   ```bash
   # Canonical check via PyYAML — catches every YAML 1.2 plain-scalar hazard
   git diff --staged --name-only -- '../documentation/docs' \
     | grep -E '\.md$' \
     | while read f; do
         python3 - "../documentation/$f" <<'PY'
   import yaml, sys
   path = sys.argv[1]
   txt = open(path).read()
   if txt.startswith('---'):
       end = txt.find('---', 3)
       if end != -1:
           try:
               yaml.safe_load(txt[3:end])
           except yaml.YAMLError as e:
               print(f'YAML PARSE FAIL: {path}: ' + str(e).split(chr(10))[0])
               sys.exit(1)
   PY
       done

   # Bash fast-fail for the `: ` hazard (the most common pattern; runs without Python)
   git diff --staged --name-only -- '../documentation/docs' | grep -E '\.md$' | while read f; do
     desc=$(head -3 "../documentation/$f" 2>/dev/null | grep '^description:' | head -1 | sed 's/^description: //')
     if [ -n "$desc" ]; then
       if echo "$desc" | grep -qE ': [a-zA-Z]'; then
         echo "YAML HAZARD ': ' in $f"
         echo "  → $desc"
       fi
     fi
   done
   ```
   For every hit: replace `: ` with ` — ` (em-dash, consistent with the existing description style) OR restructure the sentence OR wrap the whole value in double quotes. Re-check until both checks return zero output. **Do not commit a doc change whose frontmatter does not parse cleanly via PyYAML.**

7. **Verify locally** — every acceptance criterion met; every Quality Bar gate has citable evidence; outbound URLs verified per `playbooks/claim-inventory.md` step 3; tests pass.

8. **Commit** on the batch branch with the `Sources:` footer (format in `pillars/documentation/authoring.md`):
   ```
   {category}: {title} [{ID}]

   {1–3 sentence what-and-why}

   Sources:
   - Config: {file:line}
   - Builder: {file:line} ({param-status})
   - Repo: {url} → architecture.md row "{repo}"
   ...
   ```
   Footer is **mandatory** for code-backed / URL-backed / spec-backed / terminology-backed claims. Pure prose-polish writes `Sources: none (prose polish, no factual claim)` explicitly.

9. **Flip status to `review-ready`** — not `done`. Record in the item's Context: affected pages (for live-site verification), the `Sources:` footer contents, the outbound URL list, any caveats surfaced (in-scope and out-of-scope).

## Phase 3 — Close the batch

1. **Consolidate state updates** on a single odd-team branch: `DOC-XXX` frontmatter → `review-ready`; `state/file-registry.yaml`; `state/PROGRESS.md` counts (and Upstream Issues table for any new draft); `navigation/domains/*.md` if pointers shifted (especially bean factories / SDK builders discovered during the consumer-read audit); any new ADR drafts; new `backlog/{cat}/DOC-NNN.md` follow-up items; new `issues/{repo}/{PREFIX}-NNN.md` upstream drafts.

2. **Push and open PRs** — at most one per repo. Target-repo PR body enumerates each item by ID with a one-line summary; mark explicitly as **pending review**. odd-team state PR covers all bookkeeping for the batch with the same pending-review marker. **Release-gated batches**: push the train branch (same-name refspec — `retrospectives/LSN-034`) and open **no documentation PR** — `release/{version} → main` is opened once per release by `playbooks/release-train-merge.md` half 1; the handoff lists each item's expected post-merge URLs + verbatim phrases for the deferred Gate 8.

3. **Hand off to review.** The batch does not proceed to merge from this session. Report: items moved to `review-ready` (by ID); follow-ups logged (by ID — both backlog and issue drafts); `Sources:` footers (summarised); caveats surfaced; PR URLs; instruction to user to run `/review` in a separate session.

Live-site verification is **`/review`'s** responsibility (`playbooks/live-site-verification.md`), not the implementer's. Surface the live-URL list so `/review` does not have to derive it.

## When to pause and ask the user

- Acceptance criteria genuinely cannot be met → mark the item `blocked`, continue the batch; do not escalate single-item blockers.
- A documentation item classifies release-gated but no open milestone matches the unreleased behaviour → mark it `blocked`, surface (the maintainer creates or re-targets milestones — never invent one).
- A destructive or irreversible action isn't explicitly authorized.
- An ADR conflict forces a material scope decision.
- A scope-expansion judgment call ("this pulls in 5 more items — expand or split?").
- The consumer-read audit surfaces a caveat whose fix would materially expand the change.
- The batch is complete — surface one review-handoff request with the full list.

Silence is not the target; savvy judgment is. Don't bundle unrelated items, don't skip Quality Bar checks to speed through a batch, don't merge logically distinct changes into one commit, don't skip the SoT verification, **don't self-mark items `done`**.

## Reference

- Quality Bar gates → `pillars/{active}/gates.md` (documentation: `pillars/documentation/gates.md`)
- Universal-gate playbooks → `playbooks/{consumer-read,unset-parameter-audit,duplication-sweep,pre-authoring-stance,claim-inventory,live-site-verification,follow-up-on-disk,release-train-merge}.md`
- Case-law → `retrospectives/` (`retrospectives/README.md` carries an LSN-by-gate index)
- Integration patterns + canonical repos → `navigation/architecture.md`
- Batching rules → `CLAUDE.md` "Autonomous Execution and Batching"
- Work-item format + lifecycle → `backlog/README.md`