⚡ AI Pulse
← Projects · 1-week

Decision Log Weaver

A GitHub Action that automatically generates a structured ‘Decision Log’ entry from a PR’s linked agent transcripts, appended to a DECISIONS.md file in the repo.

Difficulty: 1-week | Stack: TypeScript, GitHub Actions, Octokit, Anthropic Claude API, Zod

Who this is for

Engineering teams adopting AI-assisted development who want institutional memory — product managers and future engineers can read DECISIONS.md to understand architectural choices without digging through chat logs.

Build steps

  1. Define a convention: developers paste a transcript summary (or upload a .transcript.md file) as a PR comment using a sentinel marker like <!-- transcript-start --> … <!-- transcript-end -->.
  2. Write a GitHub Action triggered on PR merge that extracts all transcript blocks from PR comments using the Octokit REST API.
  3. Send the extracted transcripts to the Claude API with a structured-output prompt (validated via Zod) requesting: problem statement, options considered, decision made, and tradeoffs accepted.
  4. Commit the resulting structured entry to DECISIONS.md in the repo using the GitHub Contents API, keyed by PR number and merge date.
  5. Add a secondary Action step that posts the generated decision summary back as a PR comment so the author can verify accuracy before the merge commit is finalised.

Risks

  • Teams won’t adopt the transcript-paste convention consistently — if fewer than half of PRs include transcripts, DECISIONS.md becomes a sparse, misleading record rather than a useful one.
  • Claude API calls on every PR merge add per-merge cost (~$0.01–0.05); at high PR volume this becomes noticeable and teams may disable the Action.
  • Structured extraction quality drops when transcripts are long, rambling, or cover multiple unrelated decisions in one session — the output conflates separate rationales.