Deliverable templates

Why every document opens with frontmatter

The block of key: value lines between two --- rules at the top of a Markdown file is called YAML frontmatter. It is metadata: what this document is, who it is for, when it was written, what it relates to.

The reason to bother is arithmetic. A model asked a question about a repository holding forty documents has to decide which ones are relevant. With frontmatter it reads six lines per file — two hundred and forty lines — and then opens the three that matter. Without it, the only way to know what a file contains is to read the file, so the model either reads all forty or guesses from the filename. The first is slow and crowds out your actual question; the second is how you get an answer drawn from the wrong document.

The same block does the same job for a human scanning a folder listing, and for you in eight months when the filename alone no longer reminds you what the document concluded.

The engagement brief

Written before any modeling. Its job is to state the problem in your own words and commit to a prediction you can be shown wrong about. A brief written after the analysis is a summary of the answer — and both you and any reader can tell.

Lives at docs/briefs/<engagement>-brief.md.

---
type: brief
engagement: perfect-competition
capability: marginal-analysis
date: 2026-08-24
status: committed          # committed | superseded
hypothesis: "Tomato-heavy mix; the labor penalty does not close the revenue gap"
---

# <Engagement> — engagement brief

## The problem
What is being decided, by whom, and what happens if it is decided badly.
What is fixed, what is chosen, and what limits the choice. In your words —
if you cannot state it without re-reading the source, you do not have it yet.

## What I am assuming
The assumptions you are taking as given, and which of them you would want
to test if you had more time.

## Hypothesis
"I expect X because Y." Real quantities, and the mechanism you think decides
it. You are not judged on being right. A hedged prediction that would survive
any outcome is the only kind that is worthless.

## How I would know I was wrong
The observation that would falsify the hypothesis above.

The last section is short and does more work than any other: naming the disconfirming observation in advance is what separates a prediction from an opinion.

The specification

Written before the artifact exists, and precise enough that somebody who has never seen your case could build it from this document alone. That is not a figure of speech: in every build stage, an AI tool does exactly that.

The spec is the prompt. Ambiguity here becomes a defect in the build, and a model will follow a vague spec as confidently as a precise one — it simply builds the wrong thing. Every minute spent making this document unambiguous is a round of corrective back-and-forth you do not pay for later.

Lives with the capability it describes, at capabilities/<capability>/spec.md, beside the model it specifies.

---
type: spec
capability: marginal-analysis
engagement: perfect-competition
date: 2026-08-26
status: built            # draft | built | audited
built_with: "Claude Code, from this file"
---

# <Capability> — model specification

## Purpose
What decision this model supports, in two sentences. What it must be able to answer.

## Inputs — the named contract
| Name | Value | Unit | Source |
|---|---|---|---|
| `TOM_PRICE` | 8800 | USD per bed | Case scenario, crop table |
| `TOM_HRS`   | 2.5  | hours per week per bed | Case scenario, crop table |

Every input gets a name, a value, a unit, and a source. You choose the names.
The requirement is that they exist and are used consistently below.

## Structure
Each sheet or region, and what it is for.

## Calculation logic
In named-range notation, never cell addresses:

  LABOR_HRS(q) = q x HRS_PER_BED x WEEKS x (1 + DIM_PCT)^q

"Column D times column E" is not a specification — it describes a spreadsheet
that does not exist yet.

## Conventions
The rules that are not visible in the formulas: costing order, allocation basis,
rounding, what happens at the boundaries. State all of them. A convention you
leave out is a convention the builder invents.

## Validation rules
The conditions the finished artifact must satisfy — check figures as acceptance
criteria, hand calculations, and structural rules ("every calculated cell
contains a formula", "no error cells").

## Outputs
Each result the model reports, by name.

## Audit findings
Added AFTER the build. For each check: what you checked, what you found, what
you did about it.

How to hand a finished spec to each AI surface is on the AI Tools Lab.

The design spec — design.json

When the artifact being generated is visual — a deck, a report, a page — the specification has a second half. The content spec says what each part argues. The design spec says what it should look like.

A design decision you leave out is a design decision the generator invents. That is the whole reason this file exists: an AI asked for "a professional deck" will produce the same professional deck it produces for everyone, because nothing in the request distinguished yours. Ten lines of specification is the difference between your work and the house style of a model.

Lives at the root of the repository that holds the artifact.

{
  "name": "Team Meridian — geopolitical case deck",
  "tone": "Consulting brief. Declarative, evidence-first, no exclamation marks.",

  "palette": {
    "background": "#0f1417",
    "surface":    "#182027",
    "text":       "#e8eef2",
    "muted":      "#93a4ae",
    "accent":     "#2f9e8f",
    "warning":    "#d98a3c",
    "_note": "Accent is used for one thing per slide. If everything is accented, nothing is."
  },

  "type": {
    "heading": "Inter SemiBold, 34pt, sentence case",
    "body":    "Inter Regular, 20pt, max 3 lines per bullet",
    "figure_caption": "Inter Regular, 14pt, muted",
    "_note": "No slide has more than 30 words of body text."
  },

  "layout": {
    "grid": "12-column, 60pt margins",
    "title_position": "top-left, never centered",
    "figure_rule": "One figure per slide, right half, caption beneath",
    "empty_space": "At least 30% of each slide. Density is not rigor."
  },

  "rules": [
    "Every slide states a claim in its title, not a topic.",
    "No slide repeats a number that appeared on the previous slide.",
    "Sources appear as a short cite on the slide, in full on the references slide."
  ]
}

Audit the generated artifact against this file the same way you audit a workbook against its spec: rule by rule, naming what each check would have caught. When it fails, fix the spec and regenerate — not the slide.

The decision memo

Written after the analysis, addressed to whoever has to act. It is not a summary of what you did; it is a recommendation with the reasoning attached, short enough that a busy reader finishes it.

Lives at docs/decisions/<engagement>-memo.md.

---
type: memo
engagement: perfect-competition
capability: marginal-analysis
date: 2026-09-04
audience: "The owner-operator"
recommendation: "Plant 10 tomato, 20 carrot, 30 mesclun"
evidence: analysis/perfect-competition-analysis.md
---

# <Engagement> — recommendation

**Recommendation.** One sentence. The thing you want done.

## Why
The two or three reasons that actually drive it, each pointing at a number in
the analysis. Not every finding — the ones that change the decision.

## The judgment call
Where the evidence ran out and you decided anyway. Every real recommendation
has one; naming it is what makes the rest credible.

## What would change my answer
The observation, price, or constraint that would flip this. This is the section
a reader returns to when conditions change.

Briefs ask; memos answer. If your memo restates the question rather than resolving it, or your brief describes what you found, they have swapped jobs.

The prompt log

One file at the repository root, appended to as you go — not reconstructed the night before a deadline, which produces a document that is fiction and reads like it. Log the sessions that changed what you did.

Lives at prompt-log.md.

---
type: prompt-log
owner: firstname-lastname
started: 2026-08-24
---

# Prompt log

| Date | Tool | What I asked | What I got | What I did with it |
|---|---|---|---|---|
| 2026-08-26 | Claude (web) | Why is my MC column falling between beds 5 and 7? | Pointed at the wage switch when permanent hours run out | Verified in the sheet; kept it and explained the dip in the analysis |
| 2026-08-27 | Claude Code | Draft the .gitignore for an Excel-heavy repo | Standard Office and OS patterns | Read it, added ~$*.xlsm, committed |

## Errors caught
- 2026-08-27 — confidently stated the medallion peak as $1.3M. Checked the TLC
  source: wrong. Recorded in AGENTS.md so it stops recurring.

The errors section is the part that is worth something later. A log claiming a model was flawless reads as a log kept by somebody who was not checking.

Naming

Name for the engagement, never for the week or the assignment number. The full naming rules are on the portfolio repo standard.

Related

• Portfolio repo standard — where each of these documents lives
• AI conventions — who drafts first, and the verification loop the prompt log records
• Git mechanics — committing, pushing, and how work is submitted