agentleFS
rust-worksrust-works/succinctly/.agents/skills/update-adr-inventory/SKILL.md

update-adr-inventory

Skill52 starsChanged 25 days agoMITView on GitHub

Update the ADR inventory table in docs/adrs/README.md by scanning all adr-*.md files, extracting their title, status, and date. Use when a new ADR is added or an existing ADR's status or title has changed.

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    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. Distinctive:

    Only touch rows that actually changed: When adding a new ADR, append a row matching the existing column widths — do NOT reformat the …

    line 13
  2. Very specific:

    Read the current inventory: Read docs/adrs/README.md and parse the existing table to understand current column widths and which ADRs are …

    line 21
  3. Distinctive:

    Determine the date: Use git to get the author date of the commit that first introduced the file:

    line 34
  4. Distinctive:

    If the file is untracked (no git history), use today's date.

    line 39
  5. Distinctive:

    If the status does not match any of the above, use the raw text as-is.

    line 51
  6. Distinctive:

    Removed ADRs: Delete only that row.

    line 59
  7. Distinctive:

    No changes: Do nothing — do not rewrite the table.

    line 60
  8. Distinctive:

    Only widen columns (header, separator, and all data rows) if new content exceeds the current column width.

    line 62

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “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

Update ADR Inventory

Rebuild the inventory table in docs/adrs/README.md so it reflects the current set of ADR files and their metadata.

Critical: Minimise diff noise

Only touch rows that actually changed. When adding a new ADR, append a row matching the existing column widths — do NOT reformat the header, separator, or unchanged data rows. When updating an ADR's status or title, edit only that row's cell content and pad to match the existing column width. The goal is a minimal, reviewable git diff.

Procedure

  1. Read the current inventory. Read docs/adrs/README.md and parse the existing table to understand current column widths and which ADRs are already listed (with their status and title).
  2. Find all ADR files. Glob for docs/adrs/adr-*.md (exclude README.md). Sort results in natural numeric order by ADR number.
  3. Extract metadata from each ADR file. For every file, read the first ~10 lines and extract:
    • ADR number and title from the level-1 heading: # ADR-NNNN: Title
    • Status from the ## Status section (the first non-empty line after ## Status)
  4. Determine the date. Use git to get the author date of the commit that first introduced the file:
    git log --diff-filter=A --follow --format="%as" -- <file> | tail -1
    If the file is untracked (no git history), use today's date.
  5. Map status text to the table format. Normalise the raw status string (strip any existing emoji) and apply the project's status legend:

    Raw (case-insensitive)Table display
    Proposed🟡 Proposed
    Accepted✅ Accepted
    Deprecated❌ Deprecated
    Superseded🔄 Superseded

    If the status does not match any of the above, use the raw text as-is.

  6. Compare and apply minimal edits.

    • New ADRs: Append a row, padding each cell to match the existing column widths (right-pad with spaces). Do not alter the header or separator rows unless the new content exceeds an existing column width.
    • Changed status/title: Edit only the affected cell(s) in the existing row, adjusting padding to maintain alignment.
    • Removed ADRs: Delete only that row.
    • No changes: Do nothing — do not rewrite the table.

    Only widen columns (header, separator, and all data rows) if new content exceeds the current column width. Never shrink columns.

  7. Report what changed. Tell the user which ADRs were added, removed, or updated compared to the previous inventory, or confirm that the inventory was already up to date.

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.

Reviews can't be read right now.

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.