agentleFS
opendatadiscoveryopendatadiscovery/odd-team/.claude/skills/implement/SKILL.md

implement

Skill0 starsChanged 2 months agoApache-2.0View on GitHub

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.

  • Commits and pushes

192 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use setup-ts-deep-modules, ask-matt and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • liufeng1976Skill

    setup-ts-deep-modules

    Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.

    Also in 43 projects that use this

  • GoogleSkill

    ask-matt

    Ask which skill or flow fits your situation. A router over the skills in this repo.

    Also in 91 projects that use this

  • RoentekSkill

    loop-me

    Grill me about specs for the workflows I want to build, within this workspace.

    Also in 50 projects that use this

  • AWSSkill

    to-questionnaire

    Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

    Also in 88 projects that use this

  • ryotaroh180105Skill

    claude-handoff

    Hand the current conversation off to a fresh background agent that picks up the work immediately.

    Also in 42 projects that use this

  • GoogleSkill

    to-spec

    Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.

    Also in 168 projects that use this

  • +3 more from google

The file

We split this skill into the rules it gives an agent

2 rules. 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 174 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

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

    line 12
  2. Distinctive:

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

    line 20

“Common” is measured: kept by at least 6 in 10 of the 174 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

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.

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.

# 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.

  1. 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.
  2. 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.
  3. 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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.