agentsclimarketplace

Madr decision log

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

AI coding agent runtime that makes LLMs understand your codebase with repository-aware context, memory, and continuous learning

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.

One thing to look at

  • 3 stars3 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.

What its author says it does

Copied from the file, not written here

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.

SKILL.md

5.2 KB, 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

Keep looking

Skills are one crate of 328,083. 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.