pbf: Skill for Claude Code

Writing an ADR for this project

An ADR earns its place by outliving the conversation that produced it. It must be readable, and checkable, by someone who was not in the room — including a future agent that has forgotten everything discussed here. That constraint drives every rule below.

Interview before drafting

Don't draft from a one-line request. Ask what's actually needed to write a decision someone else can evaluate cold:

• What is the decision, stated as a single sentence a reader could act on?
• What forces made this a decision rather than an obvious default — a constraint, a prior failure, a real trade-off?
• What alternatives were actually considered — not ones invented to fill out a section. If nothing else was seriously considered, say that; don't manufacture a rejected alternative just because the template has a place for one. A section existing to be filled is not a reason to invent its contents.
• What does this decision deliberately not cover? An ADR that doesn't state its own boundary invites scope creep in its own body later.

If the answers aren't available, ask the user rather than filling gaps with plausible-sounding content. A confident invented answer is worse than an honest gap, because it reads as settled when it isn't.

The template

Use this section set and order. If docs/adr/ already has ADRs, check two or three of them for exact heading style before writing:

# ADR-NNN: <Title>

## Status
Proposed

## Context
<the forces, the problem, why this needed a decision>

## Decision
<the decision itself, stated plainly>

## Rationale
### <reason 1, as a heading>
### <reason 2, as a heading>
...

## Consequences
### Positive
### Negative
### Accepted Trade-Off

## Rejected Alternatives
### <alternative 1, as a heading>
...

## Non-Goals
<what this decision does not cover, and doesn't try to>

Status starts as Proposed, never Accepted — see docs/adr/README.md's own convention: an ADR moves to Accepted only after a prototype or spike has exercised the decision, not on the strength of the argument alone.