agentsclimarketplace

Madr decision log

Skill ldilov/harness-forge/skills/madr-decision-log

create, review, normalize, validate, and maintain markdown architectural decision records using madr conventions. use when a repository needs durable adr files, a repeatable docs/decisions workflow, adr indexing, status updates, supersession handling, or file-based quality checks around decision records.From its SKILL.md

Install
npx -y skills add ldilov/harness-forge --skill madr-decision-log

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • 6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
  • runs commandsInstructs the agent to run 3 commands, including `python skills/madr-decision-log/scripts/new_adr.py --dir docs/decisions --title "<decision title>"` and 2 more.

SKILL.md

5.2 KB, ~1.1k tokens by cl100k_base, as published. Nobody here has run it

MADR Decision Log

Trigger Signals

  • a decision should become a durable markdown record rather than remain trapped in chat or meeting notes
  • the repository needs a docs/decisions/ practice with numbering, indexing, review, and validation
  • an ADR should be reviewed, normalized, superseded, or updated without losing historical meaning
  • the team wants a file-oriented MADR workflow rather than a lightweight one-off decision summary

Inspect First

  • existing ADRs, RFCs, design docs, and release notes that already touch the same decision
  • whether the repository already uses docs/decisions/, another decision directory, or a numbering convention worth preserving
  • whether the request is about creating a new ADR, reviewing one, bootstrapping an ADR corpus, or maintaining an existing ADR log
  • whether the repo already emits machine-readable decision indexes under runtime surfaces such as .hforge/runtime/decisions/; keep those derived artifacts separate from the authored markdown ADRs

Workflow

  1. determine the mode: create, review, bootstrap, or maintain
  2. default to authored ADR files under docs/decisions/ unless the repository already has a different documented location
  3. use the canonical template and conventions from:
    • skills/madr-decision-log/references/adr-template.md
    • skills/madr-decision-log/references/madr-reference.md
    • skills/madr-decision-log/references/review-checklist.md
  4. when repository artifacts are needed, use the packaged scripts instead of rebuilding helpers ad hoc:
    • python skills/madr-decision-log/scripts/new_adr.py --dir docs/decisions --title "<decision title>"
    • python skills/madr-decision-log/scripts/validate_madr.py docs/decisions
    • python skills/madr-decision-log/scripts/build_log.py docs/decisions
  5. preserve existing numbering, folder rules, and terminology when the repository already has an ADR practice
  6. when a decision is superseded, keep the old ADR, update its status, link the successor, and rebuild the ADR log

Create mode

  • capture the problem statement, decision drivers, considered options, chosen option, consequences, confirmation strategy, and known stakeholders
  • scaffold the file with skills/madr-decision-log/scripts/new_adr.py when the user wants repository artifacts
  • write the ADR using the MADR structure and keep option names consistent across sections
  • validate before handoff with skills/madr-decision-log/scripts/validate_madr.py

Review mode

  • compare the ADR against skills/madr-decision-log/references/review-checklist.md
  • separate structural issues, reasoning gaps, missing metadata, and wording improvements
  • keep the decision meaning intact while normalizing the document into clearer MADR shape
  • when the user asked for review only, do not silently rewrite first; report the issues and then provide a corrected version or patch

Bootstrap mode

  • create docs/decisions/ if it does not exist
  • create or propose an initial repository-level ADR such as 0001-record-architecture-decisions.md when a seed decision is useful
  • build ADR-LOG.md from the actual ADR files using skills/madr-decision-log/scripts/build_log.py
  • validate the directory using skills/madr-decision-log/scripts/validate_madr.py

Maintenance mode

  • update status and supersession links without deleting historical ADRs
  • rebuild ADR-LOG.md after filename, status, or path changes
  • treat the ADR log as a generated navigation artifact; the ADR files remain the source of truth

Output Contract

  • repository-ready MADR markdown or an explicit review report, depending on the request
  • preserved numbering and directory conventions unless a change was requested
  • validation results when files were created or updated
  • explicit note on supersession, confirmation, and follow-up links when the decision changes over time

Failure Modes

  • the task is still exploratory and no stable decision exists yet
  • the repository already has an ADR convention, but the response would overwrite it instead of extending it
  • chosen option names drift across sections and make the ADR inconsistent
  • the request mixes authored ADR files with generated runtime decision indexes and loses the source-of-truth distinction

Escalation

  • escalate when the decision changes public contracts, cross-team ownership, migration policy, or release obligations
  • escalate when a requested rewrite would change the historical meaning of an existing ADR rather than clarify it
  • escalate when the repository already has conflicting ADR practices and the owner must choose the canonical one

References

  • skills/madr-decision-log/references/adr-template.md
  • skills/madr-decision-log/references/madr-reference.md
  • skills/madr-decision-log/references/review-checklist.md
  • skills/madr-decision-log/scripts/new_adr.py
  • skills/madr-decision-log/scripts/validate_madr.py
  • skills/madr-decision-log/scripts/build_log.py

What ships with it: 6 files

15.1 KB alongside SKILL.md, 3 of them executable

scripts/

Keep looking

Skills are one crate of 611,919. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.