Alpha Forge - ADR Prompt

Source: Notion | Last edited: 2025-12-04 | ID: 2bf2d2dc-3ef...

In terms of how to generate ADR documentation, here is what we use - we use claude code to first make plans with the following prompt:

For the triple backtick quoted PROBLEM STATEMENT (PBSM) below, spawn nine (9) sub-agents in mixes of sequential and/or parallel (all reasonably determined based on the nature of the PROSTAT). Each sub-agent uses its own dynamically created todo list (DCTL) to investigate their responsible perspective, with empirical validation (uvx/uv) when needed in tmp/[problem-statement] directory. DCTL means for each sub-agent:

Start with just one (1) initial Todo List Item (TLI) based on its assigned perspective
Complete the TLI → Analyze findings → CREATE next TLI based on discoveries
Mark the TLI as completed → Execute next TLI → Repeat until questions answered
Non-pre-defined TLI emerges from findings of the last TLI naturally (i.e. DYNAMICALLY) PBSM:

<Your problem statement goes here, e.g., help me to build a new plugin to load data from DB>

After your subagents researching and thoroughly probing the internet, local workspace, and related packages, etc; on any ambiguity, discrepancy, or uncertainty, start an iterative clarification and deep-analysis loop: in each cycle, generate as many multiple-choice questions (each with clear options, a highlighted recommendation, and concise justifications) as required — evidence-driven during analysis/review or exploratory during design/ideation — refine and deepen with my replies (read-only exploration allowed, no silent assumptions), and continue iterating until I respond LGTM/lgtm, signaling approval to proceed autonomously while keeping the clarification loop open for any new issues. ultrathink

Then you’ll interact with Claude to generate a well-thought plan, once the plan is generated, use the following prompt to move to the implementation phase:

Implement the plan but first by writing ADR+spec, docs-as-code: MADR /docs/adr/YYYY-MM-DD-slug.md; spec /docs/design/YYYY-MM-DD-slug/spec.md. with adr-id=YYYY-MM-DD-slug in Google Design Doc format;

Keep ADR:left_right_arrow:spec:left_right_arrow:todo list:left_right_arrow:code in sync.
No backward-compatbility / legacy code needed
Doc style: no promo + abstractions over implementation.
SLO: availability/correctness/observability/maintainability (no speed/perf/security)
Errors: raise+propagate; no fallback/default/retry/silent.
Auto-validate outputs/artifacts.
Abstract all magic numbers into semantic, version-agnostic dynamic constants.
in md files, use the form descriptive text, never ./ or ../ paths ultrathink