decision-table

Decision Table

Purpose

Generate a repo-local decision-table artifact that makes control-flow and stateful edge cases reviewable. The decision table is the source of truth; a Mermaid diagram is optional and secondary.

Output Location

Write artifacts under <repo-root>/.closedloop-ai/decision-tables/. Create the directory if missing.

Default to one artifact per work item:

• plan-scoped: <plan-id>.md
• non-plan-scoped: <short-work-name>.md (lowercase kebab-case)

Keep multiple behavior areas as sections inside the same artifact. Only split into multiple files when one artifact would be too large to review quickly or when the work clearly spans separate repos/systems.

Workflow

1. Resolve the repo root and the work item under review.
2. If a plan/ticket/description is supplied, infer behavior to map: control-flow surfaces, retries/recovery/finalization, validation/error paths, state transitions, durable side effects. Ignore purely mechanical edits.
3. Read the plan first (if any) and extract only behaviorally relevant requirements.
4. Read repo-level guardrails as co-equal requirements: agent instruction files (AGENTS.md, CLAUDE.md), compatibility rules, contributor docs, API contracts. If the plan and guardrails conflict, record the tension in the artifact, add a Plan Clarifications note when appropriate, and surface the conflict to the user if it affects implementation or review.
5. Read the actual code paths. Build the table from code, not expectations.
6. For shared routes, handlers, helpers, contracts, or policy surfaces, build a call-site inventory before choosing axes. Search for literal route paths, exported helper names, feature flag keys, rollout keys, query parameters, cache key segments, environment variable names, storage keys, event names, command names, plugin or marketplace identifiers, header/reason/status strings, and shared types. For each caller, record what data it can supply, what response shapes/statuses it expects, peer version skew, and how missing/unknown fields degrade. Classify each literal by semantic purpose and source of truth; do not treat similar-looking strings as aliases unless a shared constant, documented contract, or existing compatibility path proves they are aliases.
7. For dependencies, model success, null/absent, validation failure, and thrown/rejected branches whenever externally visible behavior depends on them.
8. Run the behavioral edge-case expansion pass. Apply every category in references/edge-cases.md. Each must be represented by rows or an explicit non-applicability note with source-backed evidence. When multiple evidence, authority, history, or fallback sources can coexist, add a bounded interaction pass: cover pairwise and high-risk intersections instead of an unbounded Cartesian product, including legacy/absent plus fresh valid, corrupt/undated plus fresh valid, irrelevant historical plus current authoritative, tied/conflicting current records, and source/state precedence. For distributed command, signing, key, capability, or cross-process state work, treat web app, backend, Electron, local store, OS notification, cache, and remote peer behavior as separate surfaces unless code proves they are the same surface.
9. Choose a small set of state axes that explain the branch behavior. Reuse the same axes within a behavior area across Current Code and Intended Change.
10. Write the artifact using references/artifact-format.md.
11. When a plan is in scope, include Current Code, Intended Change, Delta Checklist, and Required Tests. When no plan is in scope, omit Intended Change and focus on the current-state table plus gaps or suspicious branches.
12. Give every material decision row a stable row ID. For Required Tests, map each test to one or more row IDs and name the invariant being proved, the positive path, and the wrong-input, mixed-state, failure, or compatibility mutation. A test must prove the specific binding/fallback/diagnostic the row claims; it cannot just trigger a generic rejection. When a row depends on an exact external contract literal, the test oracle must fail closed for the wrong literal: feature-flag mocks enable only the exact expected key, query/header/event assertions check exact names and values, and cache/storage/command/plugin identifiers are asserted by semantic type rather than broad substring or "any key" matching.
13. Once implementation begins, freeze Current Code and Intended Change. All later updates are append-only in Verification Findings, Fixes Applied, Final Alignment Status, and optional Plan Clarifications.
14. After implementation, verify the final code against the intended behavior. If drift, missing edges, missing tests, or guardrail violations exist, fix them, append the verification/fix sections, and re-verify until aligned. Final Alignment Status: Not aligned is a terminal stop: do not proceed to PR creation, merge, completion, or any downstream success state while it remains. Fixable repo-local findings remain unresolved work and must be fixed and re-verified; they cannot be normalized into a successful handoff.
15. Record evidence artifacts for high-yield coverage and non-applicability claims. Use references/artifact-format.md and capture the actual command or source evidence for changed exports, package subpaths, CLI flags, route/query/header/event/cache/storage/command literals, path or filesystem writes, untrusted input fields, persisted schema fields, replay/idempotency behavior, and test-boundary coverage. Do not accept an assertion such as "no consumers", "not externally visible", or "covered by tests" without the corresponding evidence.
16. Run the adversarial responsibility split described below. When delegation is available, this is a post-implementation review by independent lane workers. When delegation is unavailable, run the applicable lanes sequentially and record that the pass was not independent.
17. Group Fixes Applied by discovery source when more than one source exists (e.g., Initial verification, Adversarial abuse/filesystem lane, Adversarial compatibility lane, Runtime testing, Review findings, Validation failures, Repo guardrails, Plan clarification, Final hygiene). Do not leave a broad During verification bucket once other sources have produced fixes.
18. Treat Verification Findings as a resolution queue, not a backlog. Every finding must be (a) fixed, (b) marked not applicable with source-backed evidence, or (c) carried into Final Alignment Status: Not aligned with a specific human/external blocker (credentials, deployment access, product decision, unavailable independent adversarial review, etc.). Do not record fixable repo-local work as a permanent gap when the user asked for implementation.
19. Before marking final alignment, run two passes:
    • Internal consistency: if the same state, reason, or dependency failure appears with different intended outcomes, add the missing distinguishing axis or fix the mismatch.
    • Review-prevention: for every touched externally visible surface, walk references/review-prevention.md. Each item must be fixed, already covered by a named row/test, marked not applicable with source-backed evidence, or carried into Not aligned. Do not mark Aligned while any item is merely assumed covered.
    • Coverage and evidence disposition rule (hard rule): every Covered or already covered disposition, whether it appears in Verification Findings, in the Behavioral Edge-Case Expansion, in the adversarial lanes, or in the review-prevention pass, must cite a specific test name and the wrong-input or negative case that test fails closed on. Every not applicable disposition must cite source-backed evidence such as grep output, export/package inventory, call-site inventory, schema/query inventory, or code references proving the surface is absent or out of scope. A coverage claim backed only by a happy-path assertion, a pure helper test for an integration boundary, or no evidence is treated as Not aligned, not as covered. This applies to security findings: do not mark a security finding Covered without a named test proving the rejected or blocked case.
20. Only change Intended Change post-implementation if the plan itself was ambiguous or wrong. Record this as Plan Clarifications with reason and source. Never silently rewrite the target.
21. Always give the user a human-facing closeout summary outside the artifact. Separate: what was verified and fixed, important nuances, and anything still requiring user input or external action. When status is Not aligned, explicitly state that downstream PR/merge/completion is blocked, name every unresolved blocker, and give the exact next action and owner; never phrase it as completion. If the agent cannot complete something autonomously (product decision, credentials, deployment access, independent adversarial review), ask the user directly. If no user action is required, say so. If the user also asked for review, use the artifact as a first-class input rather than recreating the analysis.