Decision Log Entry Formatting Demonstration Prompt

This prompt is designed for engineering teams that maintain Architecture Decision Records (ADRs) or project decision logs. It uses few-shot examples to teach a model the precise formatting required for a decision entry, including context, options considered, rationale, and consequences. Use this when you need consistent, structured decision documentation from unstructured meeting notes, chat threads, or design discussions. It is not a replacement for human decision-making; it formats and structures the record of a decision that has already been made. The prompt assumes you have a clear decision statement and the raw context in which it was made.

The ideal workflow starts with a human-authored decision title and a collection of raw source material—meeting transcripts, Slack threads, design doc comments, or verbal notes. The prompt transforms that material into a standardized record. Do not use this prompt when the decision itself is still under debate, when you need the model to recommend a course of action, or when the source material contains conflicting accounts that haven't been reconciled by a human. The prompt formats; it does not adjudicate. For high-stakes architectural decisions with compliance or regulatory implications, always require human review of the formatted output before it enters the permanent record.

Before using this prompt, gather your inputs: a concise decision statement, the raw discussion context, and any constraints or principles that guided the outcome. If your team already uses a specific ADR template (such as Michael Nygard's format or a custom variant), adapt the few-shot examples in the prompt to match that schema exactly. The prompt's value comes from example fidelity—the closer the demonstrations match your target format, the more reliable the output. For teams new to decision logging, start with the default template and iterate on the example set as you discover which fields your reviews actually need.

This prompt template uses few-shot demonstrations to teach the model the exact structure, tone, and completeness expected for decision log entries. Instead of relying on verbose formatting instructions, the examples show the model how to extract context, options, rationale, and consequences from unstructured meeting notes or design discussions. The square-bracket placeholders let you swap in your own input, output schema, and domain-specific examples without rewriting the core instruction.

textCopy
You are a technical documentation assistant that formats architecture decision records (ADRs) from meeting notes, design discussions, or proposal documents.

Your task is to produce a structured decision log entry following the exact format shown in the examples below.

[OUTPUT_SCHEMA]

[EXAMPLES]

Now, format the following input into a decision log entry matching the structure demonstrated above.

[INPUT]

Return only the formatted decision log entry. Do not add commentary, explanations, or markdown fences around the output.

Placeholder Guide:

• [OUTPUT_SCHEMA]: Define the expected fields. For ADRs, include: Title, Status (Proposed/Accepted/Deprecated/Superseded), Context, Decision, Options Considered (as a list with pros/cons), Consequences, and Related Decisions.
• [EXAMPLES]: Provide 2-3 complete input-output pairs. Each example should show a raw input (meeting notes, Slack thread, design doc excerpt) and the corresponding formatted ADR. Include at least one example where multiple options were seriously considered and one where the rationale addresses a non-obvious constraint.
• [INPUT]: The raw source material to format. This could be meeting transcripts, ticket descriptions, or proposal documents.

To adapt this template for your team, replace the example pairs with decisions from your own project history. Choose examples that reflect your team's actual decision complexity—include trade-offs that weren't obvious, options that were rejected for good reasons, and consequences that materialized later. This grounds the model in your domain's real constraints rather than generic software architecture patterns. If your team uses a specific ADR tool or template (such as MADR, Y-statements, or a custom Confluence format), update the [OUTPUT_SCHEMA] to match those field names and structure exactly.

Before deploying this prompt in a production documentation pipeline, validate the output against three criteria: field completeness (all required fields present and non-empty), option coverage (every option mentioned in the input appears in the Options Considered section), and rationale grounding (every claim in the Decision and Consequences sections can be traced to evidence in the input). Run these checks programmatically after generation. If the input contains conflicting information or missing context, the model should flag uncertainty rather than fabricate a clean but inaccurate record. For high-stakes architectural decisions, always require human review before the entry is published to your decision log.

This prompt is designed to be called programmatically from an application that collects raw decision context—meeting notes, Slack threads, design doc excerpts, or freeform engineer notes—and needs a consistently formatted Architecture Decision Record (ADR) or project decision log entry. The harness should treat the prompt as a structured transformation step in a pipeline, not a standalone chat interaction. The application is responsible for assembling the [CONTEXT] and [EXAMPLES] placeholders before calling the model, and for validating the output against the expected schema before writing it to the decision log repository.

Validation and retry logic is critical because decision logs are often used for compliance reviews, onboarding, and architectural audits. The application should parse the model's output as JSON and validate: (1) all required fields are present (context, options_considered, decision, rationale, consequences), (2) options_considered is a non-empty array with at least two entries, (3) rationale references specific trade-offs rather than generic statements, and (4) consequences includes both positive and negative impacts. If validation fails, the harness should retry once with the validation errors appended to the prompt as [CONSTRAINTS] feedback. After two failures, escalate to a human review queue rather than silently accepting a malformed record. For high-stakes domains (infrastructure, security, compliance), always require human approval before the entry is committed to the canonical log.

Model choice and tool integration depend on your latency and quality requirements. For most teams, a capable mid-tier model (GPT-4o, Claude 3.5 Sonnet) with JSON mode enabled is sufficient. If your decision log is stored in a git repository or wiki, wire the validated output into a file creation or pull request workflow. For teams using RAG, you can optionally retrieve related past decisions and inject them into [CONTEXT] to help the model maintain consistency with prior architectural choices. Avoid using this prompt for real-time decision support where latency is critical—it's designed for asynchronous, post-meeting documentation. Log every invocation with the prompt version, model used, validation pass/fail status, and whether human review was required to build an audit trail for your decision log pipeline.