Telamon Create Adr

Step 2 — Determine ADR number

List files in .ai/local/ADRs/. New number = highest ADR-NNN + 1, zero-padded to three digits.

Step 3 — Derive filename

Pattern: ADR-{NNN}-{kebab-case-title}.md

Title: short, present-tense imperative phrase, <50 chars, lowercase kebab-case, no articles unless essential.

Example: .ai/local/ADRs/ADR-015-enforce-cursor-based-pagination.md

Step 4 — Write the ADR

Use the template at ./_template.md. Match the style of existing ADRs, if any.

Structure

Header:

# {Title}

Created by: Herberto
Created time: {Month DD, YYYY H:MM AM/PM}
Last edited by: Herberto
Last updated time: {Month DD, YYYY H:MM AM/PM}

Summary — structured paragraph:

**In the context of** {use case}
**facing**
- {concern}
**we decided for** {chosen option}
**to achieve**
- {quality/benefit}
**accepting** {key downside/trade-off}.

Context — 3-5 paragraphs: current state, why decision is needed, anti-patterns/failure modes, what ADR establishes. Do not name the chosen option here.

Options — at least two, mark chosen with (decided):

### Option N — {Name} (decided)
{Description}
**Pros**
- {argument}
**Cons**
- {argument}

Decision — opens with "We adopt Option N: ...", explains why, uses comparison tables when applicable.

Design Constraints — each constraint: ### Heading + paragraph. Ends with ### Rationale numbered list (bold titles + explanation paragraphs).

Consequences and Follow-Up Work — opens with "To implement this decision, we need to:", followed by actionable tasks. Ends with:

### Proponents: {name(s)}
### Deciders: {name(s) or [pending review]}
### Date: {YYYY-MM-DD}

Step 5 — Save

Write to .ai/local/ADRs/{filename}.md. Confirm file path and title to the user.

Quality Checklist

• Filename follows ADR-{NNN}-{kebab-case-title}.md
• Title is present-tense imperative, <50 chars
• Summary uses exact structured format
• At least two options, chosen marked (decided)
• Pros/cons are specific, not generic
• Decision opens with "We adopt Option N:"
• Every Design Constraint has heading + paragraph
• Rationale items numbered with bold titles
• Follow-up tasks are concrete and actionable
• Proponents, Deciders, Date filled in
• No template section missing or empty

Style Rules

• Clear, direct, third-person technical prose. No first-person.
• Bold for key terms being defined or distinguished.
• Tables for comparing across multiple dimensions.
• Code blocks for URLs, JSON, config snippets.
• ## for top-level sections, ### for sub-sections.
• No sections beyond the template. No emoji.