# Encoding order and gotchas

Web page: https://academy.memberpress.ai/courses/skills-as-sops/l6/

Lesson 6 of 11 in [Skills as Standard Operating Procedures](https://academy.memberpress.ai/courses/skills-as-sops/), 22 min.

Video: https://www.youtube.com/watch?v=iLqzk_3SiVI

The hardest part of writing a skill is not listing what to do — it is being honest about what order things happen and what to do when any step fails. Most skills fail not because the happy path was wrong but because the failure path was not written.

**What this actually is**

Order encoding is the practice of making sequential dependencies explicit in the procedure text. Gotcha encoding is the practice of anticipating failure modes before they happen and writing the recovery for each one.

These two practices together are what separate a skill file that works reliably from one that works once and then fails in a way that is hard to diagnose.

**Order-dependent operations**

Some steps must happen in sequence. Others can happen in parallel. The skill file must make the distinction explicit, because an agent left to its own devices may parallelize steps that cannot be parallelized, or serialize steps that could safely run together.

Here is a deployment pipeline with explicit ordering:

```markdown
## Procedure

1. Run tests: `npm test` — must exit 0 before proceeding to step 2
2. Build the site: `npm run build` — depends on step 1
3. Deploy to staging: `npm run deploy:staging` — depends on step 2
4. Run smoke tests: `npm run smoke:staging` — depends on step 3; wait 60s after deploy before running
5. Deploy to production: `npm run deploy:prod` — depends on step 4; do not run if step 4 fails
6. Notify team: post in #deployments — run after step 5 regardless of outcome
```

Step six is interesting: it runs regardless. That is not an oversight — it is an explicit decision that the team wants to know about failures too. If you leave out "regardless of outcome," an agent may skip the notification when the deploy fails, which is the opposite of what you want.

**Parallel-safe steps**

When steps can run in parallel, say so:

```markdown
3a. Lint: `npm run lint` — can run in parallel with 3b
3b. Type-check: `npm run typecheck` — can run in parallel with 3a
4. Both 3a and 3b must complete before proceeding
```

The agent will parallelize when you give permission. Without explicit permission, assume sequential.

**Gotcha encoding**

A gotcha has three parts: the trigger, the symptom, and the recovery. All three must be present for the gotcha to be useful:

```markdown
## Gotchas

- **Trigger**: Step 3 fails with "ECONNREFUSED"
  **Symptom**: The staging server is not accepting connections
  **Recovery**: Check `pm2 status` on the staging server — if the process is stopped, run `pm2 restart all`

- **Trigger**: Step 4 smoke tests fail on `/api/health`
  **Symptom**: The staging deploy succeeded but the API is not responding
  **Recovery**: Check staging logs: `pm2 logs api --lines 50` — look for startup errors

- **Trigger**: Step 5 fails with "insufficient permissions"
  **Symptom**: The deploy account cannot write to production
  **Recovery**: Verify the deploy key is still valid: `ssh-keyscan deploy.yourapp.com` — if the key is rejected, rotate via the ops runbook
```

Each gotcha is specific about where in the procedure it applies and what evidence to look for. "Something went wrong — check the logs" is not a gotcha. It is an absence of gotchas.

**If you get stuck**

If a step has a dependency that is not obvious from the procedure: add a comment inside the step. "Note: this step uses the output of step 2 — specifically the `build-id` file in `dist/`."

If you are not sure whether two steps can be parallelized: default to sequential. Add the parallel permission only after you have verified that the steps do not share a resource.

If a failure mode is too rare to write a gotcha for: write it anyway. Rare failures have the worst recovery paths precisely because nobody has documented them.

**Cross-reference**

L11 (Banned patterns) extends the gotchas concept to an automated gate — a script that catches specific failure modes before human review.

**Deliverable**

Revise your skill file from L5 to add explicit ordering annotations to every step that has a dependency, and expand the gotchas section to at least five entries with trigger, symptom, and recovery for each. The success criterion: someone unfamiliar with the procedure can read the gotchas and know what evidence to look for at each failure point.

## Try these prompts

- Write a deployment procedure with six steps where three steps have explicit sequential dependencies and two steps can run in parallel. Mark both the dependencies and the parallel permission in the step text.
- Write three gotchas for a skill that uploads files to an S3 bucket. Each gotcha must include the trigger, the symptom, and the exact recovery command.
- A step in my skill says "notify the team after deploying." Rewrite it to specify whether it should run even when the deploy fails, and what channel and message format to use.

Next: [Practice - document a complex procedure](https://academy.memberpress.ai/courses/skills-as-sops/l7/)