Workbook guide

Complete reference for filling the Architecture Review collection workbook. Each sheet's purpose, column descriptions, and allowed values are documented below.

Quick start: Download the blank workbook or sample filled workbook. Fill sheets in order: Review → Evidence → Technology → Trajectories → (optionally) Findings → Actions. Do not rename sheets or headers.

Controlled values reference

These dropdown lists appear in coloured header cells. Use the arrow to select — do not type free-form values.

Field	Allowed values	Where used
`severity`	`critical` `high` `moderate` `low`	Findings
`confidence`	`high` `medium` `low`	Findings
`horizon`	`before-production` `next` `later` `observe-accept`	Findings, Actions
`effort_band`	`S` (small) `M` (medium) `L` (large)	Findings, Actions
`state` (Evidence)	`requested` `received` `verified` `asserted` `missing` `superseded`	Evidence
`version_status`	`verified` `unverified` `unknown`	Technology
`status` (Trajectory)	`planned` `partial` `complete` `blocked`	Trajectories
`status` (Hypothesis)	`open` `supported` `confirmed` `rejected` `parked`	Hypotheses
`phase`	`contain` `correct` `harden` `observe`	Actions
`status` (Action)	`proposed` `accepted` `in-progress` `complete` `deferred` `rejected`	Actions
`verdict`	`undetermined` `proceed` `proceed-with-conditions` `do-not-proceed`	Review

ID patterns

All IDs follow a strict pattern. The importer rejects IDs that do not match.

Type	Pattern	Examples
Evidence	`E-###`	`E-001`, `E-042`
Technology	`TECH-###`	`TECH-001`, `TECH-015`
Trajectory	`T-###`	`T-001`, `T-003`
Hypothesis	`H-###`	`H-001`
Finding	`F-###`	`F-001`, `F-012`
Action	`A-###`	`A-001`, `A-007`
Decision	`D-###`	`D-001`

Instructions

Read-first guidance. Not imported.

Contains step-by-step instructions, tips, and security reminders. No action required.

Review

Frame the engagement: system, decision, scope, and stakeholders.

Column	Description	Required	Example
`field`	Field name (auto-filled)	auto	`title`
`value`	Your entry	required for most fields	`Claims Triage Agent`
`guidance`	Column description (auto-filled)	auto	`Client-facing review title.`

Key fields: title, production_decision, system, lifecycle_stage (prototype/pilot/production/redesign), verdict (dropdown).

Evidence

List each trace, log, diagram, deployment note, or eval result.

Column	Description	Required	Example
`id`	Stable evidence ID	required	`E-001`
`title`	Brief description	required	`Interrupted run trace`
`kinds`	Semicolon-separated tags	optional	`trace; run-log`
`state`	Evidence state (dropdown)	required	`verified`
`source_role`	Who provided it	optional	`agent-runtime`
`environment`	Where captured	optional	`pilot`
`version`	System or evidence version	optional	`1.4.2`
`captured_on`	Date (YYYY-MM-DD)	optional	`2026-08-20`
`path`	File or location	optional	`traces/run-001.json`
`notes`	Additional context	optional	`Retry duplicated external write`

Technology

Inventory of deployed components: orchestration, models, vector DB, tools, state stores, observability.

Column	Description	Required	Example
`id`	Stable technology ID	required	`TECH-001`
`category`	Component category	required	`orchestration`
`name`	Product or framework	required	`LangGraph`
`version`	Exact deployed version	required	`0.2.5`
`version_status`	Verification state (dropdown)	required	`verified`
`deployment`	Hosting mode	optional	`service`
`configuration_evidence`	Semicolon-separated config notes	optional	`checkpoint_store=postgres; retries=bounded`
`catalog_entry`	Framework catalogue reference	optional	`langgraph`
`state_owner`	Who owns state	optional	`agent`
`retry_timeout_notes`	Retry/timeout behavior	optional	`idempotency test on tool calls`
`known_constraints`	Known limitations	optional	`shared history amplifies cost`
`notes`	Additional context	optional	`See E-001`

Trajectories

Representative runs: what triggers them, how they end, what state they produce.

Column	Description	Required	Example
`id`	Stable trajectory ID	required	`T-001`
`name`	Brief description	required	`Approve claim`
`classes`	Semicolon-separated classes	optional	`approval; state-change`
`status`	Trajectory state (dropdown)	required	`complete`
`trigger`	What starts this run	optional	`Claims approver submits decision`
`terminal_state`	End state	optional	`claim_status=approved`
`notes`	Additional context	optional	`History includes prior denied claim`

Hypotheses

Framework limitations or suspected failure paths awaiting engagement evidence.

Column	Description	Required	Example
`id`	Stable hypothesis ID	required	`H-001`
`title`	Brief description	required	`History sharing amplifies cost`
`status`	Hypothesis state (dropdown)	required	`open`
`trajectories`	Related trajectory IDs	optional	`T-001; T-002`
`evidence`	Related evidence IDs	optional	`E-001`
`catalog_claims`	Framework catalogue references	optional	`autogen:AUTOGEN-LIM-001`
`notes`	Additional context	optional

Findings

Evidence-backed failure paths with severity, confidence, and recommended capability.

Column	Description	Required	Example
`id`	Stable finding ID	required	`F-001`
`title`	Brief description	required	`Retry duplicates external write`
`claim`	What is wrong	required	`Duplicated tool call creates second charge`
`severity`	Production impact (dropdown)	required	`high`
`confidence`	Evidence strength (dropdown)	required	`high`
`trajectories`	Related trajectory IDs	optional	`T-001`
`evidence`	Related evidence IDs	optional	`E-001; E-002`
`catalog_claims`	Framework catalogue references	optional	`langgraph:LANGGRAPH-RET-001`
`observed_relevance`	Why this matters for this system	optional	`Observed in E-001`
`condition`	Precondition for failure	optional	`Retry on timeout`
`trigger`	What activates the failure	optional	`Tool call fails mid-write`
`failure`	What goes wrong	optional	`Second charge posted`
`consequence`	Production impact	optional	`Customer overcharged`
`control_gap`	Missing control	optional	`No idempotency test`
`recommendation_capability`	Required capability	optional	`Idempotency key on external writes`
`acceptance_evidence`	Proof of fix	optional	`Trace shows idempotency test`
`horizon`	When to fix (dropdown)	optional	`before-production`
`effort_band`	Effort estimate (dropdown)	optional	`M`
`owner_role`	Who owns the fix	optional	`agent-platform`

Actions

Remediation steps linked to findings, with phase, horizon, effort, and acceptance evidence.

Column	Description	Required	Example
`id`	Stable action ID	required	`A-001`
`finding_id`	Parent finding ID	required	`F-001`
`title`	Brief description	required	`Add idempotency key to charge tool`
`phase`	Remediation phase (dropdown)	optional	`correct`
`horizon`	When to implement (dropdown)	required	`before-production`
`effort_band`	Effort estimate (dropdown)	required	`M`
`owner_role`	Who implements	required	`agent-platform`
`dependencies`	Blocking actions	optional	`A-002`
`acceptance_evidence`	Proof of completion	required	`Trace shows idempotency test`
`status`	Action state (dropdown)	optional	`proposed`
`notes`	Additional context	optional

Decisions

Production decisions made during or after the review.

Column	Description	Required	Example
`id`	Stable decision ID	required	`D-001`
`date`	Decision date (YYYY-MM-DD)	required	`2026-08-26`
`decision`	What was decided	required	`Proceed to supervised pilot`
`owner`	Who decided	optional	`CTO`
`rationale`	Why this decision	optional	`High-severity findings addressed; residual risk accepted`

_Lists

Hidden sheet containing dropdown values. Do not edit.

Need help? Send the filled workbook to madhavraop@dhristhi.com with context about your system and the production decision you need to make.