How to turn a finished deployment into a playbook, runbooks and a template repo for the next customer

The last week of a deployment tends to go by in a rush: the demo, the acceptance sign-off, the handover, then on to the next customer. Three months later a second customer brings the same problem, and the team starts from a blank page again.

The FDE playbook on fde.academy splits a deployment into six phases. The last is a feedback loop, where the custom work built for each customer is gradually standardised into reusable features. An article on the Palantir model on the same site is more direct: every solution an FDE builds feeds into later product development.

The same article also names the downside. If this loop is not managed, the work slides into pure customisation and becomes very hard to scale. So the ability to package a finished project is effectively the line between contributing to the product and doing one-off customisation, customer by customer.

What can you build in one evening?

By the end you will have a documentation folder and a template repo on GitHub. As a running example, imagine you have just delivered an agent to a logistics company that reads PDF invoices and pushes the data into its ERP. The example is hypothetical, but the structure below works for any kind of project.

You need four things: a GitHub account, the old project’s repo, meeting notes or chat history from the deployment, and about three uninterrupted hours. The target structure looks like this (simplified):

fde-invoice-agent-template/
├── README.md            # what problem this repo solves, how to run it
├── docs/
│   ├── adr/             # architecture decisions, one file per decision
│   ├── runbooks/        # how-to: incident handling, operations
│   ├── explanation/     # why the system works the way it does
│   └── playbook.md      # deployment phases for a new customer
├── config/
│   └── customer.example.yaml
└── src/

The five documents to write are the README, the ADRs, the runbooks, the explanation and the playbook. The steps below cover each in turn, then package everything into the template repo.

Step 1: Record decisions before memory fades

The definition on adr.github.io is short: an Architectural Decision Record captures a single architectural decision and the reasoning behind it. Open the meeting notes and look for the points the team argued over, such as which OCR to use, batch or realtime, or whether the agent should correct data itself or wait for human approval.

# ADR-003: The agent does not write directly to the ERP; it waits for human approval

## Context
Invoice formats are inconsistent; the customer's ERP does not support rollback.

## Decision
The agent writes to a staging table; accounting approves before data is pushed to the ERP.

## Consequences
+ No incorrect data reaches the books.
- Adds a manual step; approval time needs to be measured.

## When to revisit
When a new customer's ERP has an undo API.

The “When to revisit” section is the most valuable part. It tells whoever comes next that the decision depended on conditions specific to the old customer, so a new customer may call for something different. Check: give the ADR to a colleague who was not on the project. If they finish it and still ask “why not write straight to the ERP?”, the file is missing context.

Step 2: Separate runbooks from explanation

Diátaxis defines a how-to guide as directions that take the reader through a problem or towards a result. Runbooks should be written in that spirit: every step is an action, with no explanatory paragraphs in between. Keep the “why” for docs/explanation/.

# Runbook: Invoice queue is stuck

Goal: the queue runs again and no invoices are lost.

1. Open the queue dashboard; note the number of invoices waiting.
2. Check the worker logs for the last 15 minutes, looking for OCR timeout errors.
3. If there are timeouts: switch the worker to file-by-file processing mode.
4. Confirm the number of waiting invoices is going down.
5. If it has not gone down after 30 minutes: alert the customer's on-call contact (see directory).

Understanding the cause: docs/explanation/ocr-timeouts.md

The numbers in the example are illustrative; replace them with your system’s real thresholds. Check: skim the runbook. If any step begins with “Note that the system…”, move that sentence to the explanation.

Step 3: Write runbooks with the people who will use them

Google’s SRE book, in its chapter on incident management, advises preparing in advance: develop and document incident-handling procedures early, in consultation with the people who will take part in handling incidents. In the invoice-agent example, if the customer runs the system itself after handover, those people are the customer’s IT team, not yours.

So don’t write the runbook alone and email the file. Book a 45-minute session, have the operator work through each step while you sit and watch in silence. Any step they have to ask about needs rewriting.

Step 4: Assemble a playbook by phase

playbook.md is not a copy of the ADRs. It is a map: for each deployment phase, write down what to ask the customer, which ADRs to read and which runbooks to prepare in advance. You can use the six phases of the fde.academy playbook as the frame, as long as the last phase is always the feedback loop into the product.

## Phase: Data integration
- Ask the customer: does the ERP support undo? (→ ADR-003)
- Prepare: runbooks/queue-stuck.md
- Customised for the previous customer: parser for a custom invoice template
  → candidate for the product (core team notified)

That last line is where the Palantir-style loop actually happens: a solution from the field is reviewed by the core team and turned into a product capability. Each time you write “candidate for the product”, you pull the project out of the pure-customisation trap.

Step 5: Build a template repo, don’t fork

GitHub’s documentation says that anyone with access to a template repository can create a new repo from it. A repo created this way starts with a single commit. A fork is different: it carries the full history.

For FDEs this difference matters. The old project’s commit history may contain the customer’s name, internal endpoints, or a sample CSV file that someone committed by mistake and then deleted.

The cleanest process is to create a new repo, copy over only the cleaned code, replace every customer-specific value with customer.example.yaml, then turn on template mode in the repo settings.

Check: create a test repo from the template, open the commit history and confirm there is only one commit. Then search the whole codebase for the old customer’s name, their domain and words such as “prod”. The results should be empty.

Three mistakes that make the documentation useless

The first is treating runbooks as a textbook. The SRE book’s chapter on training on-call engineers lists training solely through procedures, checklists and playbooks as an anti-pattern.

Runbooks help people carry out the right steps; the explanation/ folder helps them understand why. When an incident looks like none of the written steps, only that understanding will save them.

The second mistake is forking the old customer’s repo to save time, dragging its whole history along. The third is recording only “what” and skipping “why”. Without ADRs, the next customer inherits decisions that only made sense in the old customer’s circumstances.

Where does this skill show up in hiring?

When reading FDE job descriptions, you may meet the feedback loop above under various names. Look for passages about bringing lessons from the field back to the product team, or building assets reused across customers: that signals a company needs exactly this skill.

On your CV, don’t just write “deployed system X for customer Y”. Be more specific, for example: “packaged the project into a template repo, ADRs and runbooks; the next customer reused it without rewriting from scratch”. If you can, include a link to a cleaned, public template repo. In interviews, pick one ADR and walk through the debate behind it.

On day one at a new customer, the first thing to open is the previous project’s playbook.md, not the IDE. A delivered project only becomes a team asset when the next person can reuse it.