AGENT SKILL

adr-decision-record

Produce the board's ADR-style decision record on explicit request only, using six fixed sections, with the markdown file as the canonical source and the Word document rendered from that same content so the two cannot drift.

License 许可
Apache-2.0
所属仓库
cwik-tech/octopus
最近更新
2026-10-27
Stars
★ 0
Forks
0

01 前言 Front Matter

name
adr-decision-record
description
Produce the board's ADR-style decision record on explicit request only, using six fixed sections, with the markdown file as the canonical source and the Word document rendered from that same content so the two cannot drift.

03 SKILL.md 正文

ADR Decision Record

Purpose

The architecture board is exploratory. Its default output is a better-understood problem, not a document. This skill defines the one artifact it produces, when that artifact is allowed to exist, and how to keep the markdown and Word versions from diverging.

The trigger rule — on request only

Produce a decision record only when the user explicitly asks for one.

This is a hard gate, not a strong preference.

  • Do not produce a record because the discussion reached a conclusion.
  • Do not produce a record because the session ran long or felt substantial.
  • Do not offer, hint at, or pre-draft one. "Want me to write this up?" at the end of a session is a soft violation of the same rule — it converts an exploratory board into a documentation pipeline by suggestion.
  • Sessions that end in open discussion with no artifact are successful sessions.

What counts as an explicit request: a direct ask for an ADR, a decision record, a write-up, or a document capturing the session. Ambiguous signals — "good, that settles it", "let's go with that" — do not count. If a request is genuinely ambiguous, ask once, in one line.

Canonical source rule

Markdown is canonical. The Word document is a render of that identical markdown.

  • Write the record once, as markdown.
  • Produce the Word export from that same content, unaltered.
  • Never author, edit, or extend the Word document independently.
  • Never let the Word version carry a section, a caveat, or a phrasing the markdown lacks.
  • If the record needs a change, change the markdown and re-render. There is no path where the Word file is edited directly.

The entire point is that a reader of either file is reading the same record. Any divergence, however small, destroys that guarantee for every future session.

The six sections

The record has exactly these sections, in this order. No additions, no omissions.

1. Context

What prompted the question, and what constraints were in play. Include:

  • The load-bearing question, stated as the board classified it — and the question as originally asked, if the two differ.
  • The constraints that shaped the discussion: scale, team, timeline, existing system, compliance, cost.
  • What was already fixed and not up for debate.

Write this so a reader six months out understands why the question mattered without needing the conversation. Context is where most ADRs fail — under-specified context makes the Decision unreadable later.

2. Options considered

Each option genuinely on the table, with:

  • What it is, in a sentence or two.
  • What it optimizes for.
  • What it costs.
  • Which convened seat advanced or defended it.

Include the options that lost. An ADR listing one option is not a decision record; it is an announcement. If an option was raised and dismissed quickly, include it with the reason for dismissal — that reasoning is often what a future reader most needs.

3. Decision

What the board decided, and the constraint that decided it.

  • State the decision plainly, in the first sentence.
  • Then state the deciding constraint — the single thing that made this option win over the runner-up.
  • If the board did not converge, say exactly that: "No decision. The board split on [constraint A] vs [constraint B]." A Decision section containing a manufactured decision is worse than one recording an honest non-decision. Non-convergence is a legitimate ADR outcome, and the weight then moves to Open questions.

4. Consequences

What follows from the decision, stated honestly in both directions.

  • What this makes easier or possible.
  • What this makes harder, more expensive, or foreclosed.
  • What becomes hard to reverse, and at what point reversal stops being practical.
  • What must now be true for the decision to hold — dependencies, assumptions, thresholds.

A Consequences section with only benefits means the tradeoff was not examined. Every architecture decision costs something; name it.

5. Open questions

What remains unresolved, in three groups:

  • Blocking: must be answered before the decision can be acted on.
  • Deferred: knowingly postponed, with the trigger that will bring them back.
  • Unexamined: assumptions the board relied on but nobody verified.

When the Decision section records a non-decision, this section carries the substance: what would need to be known, measured, or true to break the split.

6. Board record

The procedural trace of the session:

  • Classification: primary domain, secondary domain, load-bearing question.
  • Seats convened: each seat and what it was convened to own.
  • Overrides: any user addition or removal of a seat, recorded as instructed.
  • Re-selections: each mid-session change, with the drift that triggered it.
  • Dissent: any seat that held a minority position at the close, and what it held.

This section makes the record auditable. A future reader can see not just what was decided but who was and was not in the room — which is frequently the explanation for a decision that later looks strange.

Format template

# ADR: [Short decision title]

**Date:** [YYYY-MM-DD]
**Status:** Proposed | Accepted | Superseded
**Session:** [session id]

## Context

[Prompting question, load-bearing question, constraints in play, what was fixed.]

## Options considered

### Option A — [name]
- **What:** [description]
- **Optimizes for:** [constraint]
- **Costs:** [tradeoff]
- **Advanced by:** [seat]

### Option B — [name]
...

## Decision

[The decision, stated plainly.]

**Deciding constraint:** [the one thing that settled it.]

## Consequences

**Easier:** [what this enables]
**Harder:** [what this costs or forecloses]
**Hard to reverse:** [what locks in, and when]
**Must remain true:** [dependencies and assumptions]

## Open questions

**Blocking:** [must resolve before acting]
**Deferred:** [postponed, with return trigger]
**Unexamined:** [assumptions nobody verified]

## Board record

**Classification:** [primary] / [secondary] — [load-bearing question]
**Seats convened:** [seat] ([owns]); [seat] ([owns]); ...
**Overrides:** [any user changes to the shortlist, or none]
**Re-selections:** [mid-session changes with triggers, or none]
**Dissent at close:** [seat and position, or none]

Quality checks before emitting

  • Does Context stand alone for a reader who was not present?
  • Does Options considered include at least one option that lost?
  • Does Decision name a single deciding constraint — or honestly record a non-decision?
  • Does Consequences name a real cost, not only benefits?
  • Does Board record accurately reflect every override and re-selection from the session?
  • Is the Word export byte-equivalent in content to the markdown?

Anti-patterns

  • Volunteered records. Writing one because the session felt conclusive.
  • Single-option ADRs. A decision record with nothing rejected records no decision.
  • Manufactured decisions. Filling the Decision section when the board actually split.
  • One-sided Consequences. Benefits listed, costs omitted.
  • Independent Word edits. Any change made to the export rather than the source.
  • Thin Board record. Omitting overrides, re-selections, or dissent, which is exactly what makes the record auditable.

04 同仓库更多 Skills

cwik-tech
cwik-tech/octopus

twenty-year-land-plan

Apply the Bren discipline of evaluating every land and development decision on a twenty-year horizon, with a comprehensive plan for how the land, the community, and the surrounding public infrastructure evolve together. Deals optimized for a five-year exit are structurally different from deals that compound across generations; insist on knowing which kind you are making. Use when evaluating land, entitlements, master-planned development, or phasing decisions, and when separating five-year exit deals from generational holds.

★ 0
cwik-tech
cwik-tech/octopus

thematic-gut-check

Apply the Gray discipline of identifying the structural theme behind every real estate deal, testing where that theme sits in its capital-flow lifecycle, and insisting that deals without a named theme — or deals late in a crowded theme — clear a higher bar. A mediocre deal in a strong theme usually beats a clever deal in a weak one. Use when naming the structural thesis behind a deal, judging whether that theme is early or crowded, and setting the bar the deal must clear.

★ 0
cwik-tech
cwik-tech/octopus

supply-pipeline-gut-check

Apply the Zell discipline of grounding every real estate thesis in the local supply pipeline. Demand counts over adjectives — units under construction, units permitted, units proposed — and convert them into a forward absorption schedule. A deal that ignores the pipeline is a bet on a market you have not actually studied. Use when validating a market thesis, forecasting absorption and rent growth, or counting units under construction, permitted, and proposed.

★ 0
cwik-tech
cwik-tech/octopus

ruin-scenario-mapping

Apply the Taleb discipline of identifying, for every real estate deal, the specific chain of events that produces ruin — permanent, unrecoverable capital loss — and verifying that no single such chain has non-trivial probability. Deals with any plausible ruin path must be restructured or abandoned. Use when sizing leverage, testing refinancing, covenant, and liquidity risk, or checking whether any single failure chain can permanently wipe out the position.

★ 0
cwik-tech
cwik-tech/octopus

revenue-cost-architecture

Design a venture's revenue streams, pricing logic, cost structure, and unit economics so the business model has a coherent theory of value capture, not just value creation. Use after the value proposition and customer segment are set and before financial projections, when choosing a pricing model, calculating contribution margin or CAC payback, or checking whether the unit economics hold at scale.

★ 0
cwik-tech
cwik-tech/octopus

replacement-cost-stress-test

Apply the Buffett discipline of pricing every real estate asset against the cost to rebuild it from scratch. The ratio of purchase price to replacement cost sets a ceiling on long-run downside: below replacement cost, new supply cannot profitably undercut you; at or above it, you are buying a liability disguised as an asset. Use when setting a purchase price, judging downside protection, or testing how exposed an asset is to newly built competing supply.

★ 0