SOP Writing skill for Codex

An SOP is good when a trained person who has never done the task can complete it correctly on the first attempt using only the document, and when two different people following it produce the same result. Anything the reader has to ask about is a defect in the SOP, not in the reader.

Workflow

• Find the process owner and one person who does the task today
• Capture the current process as it is actually done (observe, screen recording, interview), not as someone thinks it is done
• Choose the format (table below)
• Draft steps, decision points, exceptions and records
• Walk through it with someone unfamiliar with the task; fix every hesitation
• Get owner approval; set version, effective date and review date
• Publish where people work (wiki, repo, tool), and retire old versions

Choose the format

Process shape	Format
Short, linear, done often by experienced staff	Checklist
Linear but detailed, done rarely or by new staff	Numbered steps with expected results
Many branches or handoffs between roles	Flowchart plus step table per role
Mostly in one software tool	Steps with exact field names and values; screenshots only where the UI is ambiguous
Technical operations for on-call engineers	Use the runbooks skill instead

SOP template

# SOP-<ID>: <Verb + object, e.g. "Process a customer refund over $500">
| Owner | Version | Effective | Next review | Approved by |
|---|---|---|---|---|
| <role, not only a name> | 1.2 | 2026-11-01 | 2027-05-01 | <name, date> |

## Purpose
<One or two sentences: why this procedure exists and what goes wrong without it.>

## Scope
Applies to: <cases>. Does not apply to: <cases, with pointer to the right SOP>.

## Roles
| Role | Responsibility in this SOP |
|---|---|

## Definitions
<Only terms a new reader might not know.>

## Before you start
- Access: <systems and permission level>
- Inputs: <documents, data, approvals needed>
- Time needed: <estimate>

## Procedure
| # | Who | Action | Expected result |
|---|---|---|---|
| 1 | Support agent | In the billing tool, open the customer and select **Refunds > New** | Refund form opens with order list |
| 2 | Support agent | Check the order date. **If over 90 days**, go to step 8 | - |
| 3 | Support agent | Enter the amount and select reason code `R2 - Service issue` | Total shown matches the request |
...

## Exceptions
| Situation | What to do | Who to contact |
|---|---|---|

## Records
<What evidence is kept, where, for how long.>

## Related documents
## Revision history
| Version | Date | Change | Author |
|---|---|---|---|

Writing the steps

• One action per step, starting with a verb: “Select”, “Enter”, “Confirm”, “Send”.
• Name exact UI labels in bold and exact values in code formatting: select Save, enter NET30.
• Put warnings and cautions before the step they apply to, not after.
• State the expected result for any step where the reader could go wrong or needs to know it worked.
• Decision points are explicit: “If X, go to step N. Otherwise continue.” Keep nesting to one level; deeper branching belongs in a flowchart.
• Specify who for every step when more than one role is involved.
• Numbers, thresholds and deadlines are exact: “within 2 business days”, not “promptly”.
• Avoid “should” and “may” for required actions; use “must” or the imperative. Use “may” only for genuine options.

Flowcharts

For branching or multi-role processes, add a Mermaid flowchart above the step table:

flowchart TD
    A[Refund request received] --> B{Amount over $500?}
    B -- No --> C[Agent issues refund]
    B -- Yes --> D{Order under 90 days?}
    D -- Yes --> E[Team lead approves] --> C
    D -- No --> F[Finance reviews exception]
    F -->|Approved| C
    F -->|Rejected| G[Agent sends decline using macro REF-DECLINE]
    C --> H[Log refund ID in ticket]

Every decision in the flowchart must match a step in the table; check both directions.

Turning tribal knowledge into an SOP

From a screen recording transcript, chat thread or interview notes:

1. List every action in order, including the “obvious” ones experts skip (logging in, choosing the right account, saving).
2. Mark every judgment call and ask the expert for the rule behind it (“how do you know it is a duplicate?”). Turn rules into decision points; judgment that cannot be turned into a rule becomes an escalation.
3. Record workarounds separately and ask whether they are intended. An SOP should not enshrine a bug or a policy violation; flag it to the owner.

Walkthrough validation

Ask someone who has not done the task to follow the draft (or simulate it step by step against the live tool in a test environment). Record:

• Every point where they hesitated, asked a question, or did something different
• Time taken versus the estimate
• Whether the final result matched the expected outcome

Fix each issue and repeat until a walkthrough completes without questions. If no tester is available, mark the SOP “not yet validated” in the header.

Regulated and audited processes

Where an SOP supports compliance (ISO 9001, SOC 2 controls, financial controls, GMP and similar), the quality or compliance owner sets the rules. Typical requirements: controlled document numbering, documented approval before the effective date, training records for people performing the procedure, periodic review, and retention of superseded versions. Ask for the organisation’s document-control procedure and follow it rather than this template’s header.

Keeping SOPs alive

• Owner is a role, so the SOP survives people leaving.
• Review date 6-12 months out; review after any incident or audit finding involving the process, and whenever the underlying tool changes.
• Store SOPs where they are version-controlled (docs repo, wiki with history); link from the tools where the work happens.
• Collect feedback with a “report a problem with this SOP” link or channel.

Gotchas

• Writing the ideal process instead of the real one; staff ignore it and the gap widens.
• Steps that bundle three actions (“open the order, check the date and issue the refund”) get partially done.
• Screenshots go stale with every UI change; prefer exact labels and use screenshots only where text cannot locate the element.
• No exceptions section: the first unusual case sends people to chat, and the answer never makes it back into the document.
• Duplicate SOPs for the same task in different places; retire one and redirect.

Output

The SOP (template above), the flowchart if branching, a walkthrough log with fixes made, and a list of open questions for the process owner (rules behind judgment calls, workarounds to confirm or remove).