# Backfill the decision record for an architecture the code already encodes

A decision the code has encoded for two years and nobody wrote down, recorded with its context and consequences.

Category: Architecture and boundaries
Source: https://letsship.ai/use-cases/backfill-an-architecture-decision-record
Published: 2026-08-25

## Goal

Write the decision record for an architectural choice the codebase already reflects.

## Acceptance criteria

- The record states the context, the decision, and the consequences
- It cites the code that implements it
- Alternatives that were rejected are named
- It is filed with the project's other records

## What lands as proof

A record that cites real code paths, so a reader can check it against the system rather than trust it.

## Prompt

Copy this to an agent to open the ticket:

```text
Create a Linear issue in my team and assign it to the SHIP agent.

Title: Write the decision record for {decision}

Description: Write the decision record for an architectural choice the codebase already reflects.

Acceptance criteria:
- The record states the context, the decision, and the consequences
- It cites the code that implements it
- Alternatives that were rejected are named
- It is filed with the project's other records

Before you create the issue, find an architectural pattern this repository follows consistently with no written rationale, and replace {decision} with it.
```

## Questions

### What does the agent actually change?

The ticket is scoped to one outcome: write the decision record for an architectural choice the codebase already reflects. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.

### How do I know the work is done?

The pull request carries the evidence, not only the diff. Here that means the record cites the code paths it describes, so a reviewer can confirm the result without reproducing the work locally.

### How much oversight does this need?

The run stops once the plan is written. Somebody reads the approach and approves it before any code exists, which is the cheapest moment to redirect the work.