Codex prompt reference

You shouldn’t have to learn Markdown cold

You own the part and its failure modes. You should not have to memorize the topic file format or escalation-path shortcode to ship a topic.

Codex (or Claude Code) edits the repo locally, in your clone, against the same files the build runs against.
It reads the repo to learn the conventions — the existing topic tree teaches it what a topic looks like.
You drive the prompt, review the diff, and stay accountable for the words a technician will read.
Beginner’s Guide to Authoring Topics with Codex walks through the first-time setup and plain-English workflow in detail.

Mental model: skill, prompt, diff, push

The loop is four steps. Same loop for every change.

Load a skill — pre-baked behaviour for a specific task.
Write a prompt — tight inputs about what you want.
Review the diff — read every changed line.
Push — open a PR and hand it to the FSE for a new guide; follow the author review path for an existing-guide edit.

The skills you’ll use most

This repo ships its own Codex skills under .codex/skills/. Three you’ll lean on:

create-topic — scaffold a new canonical topic with frontmatter, the topic object, and a connected step graph.
add-version-branch — add a software-version-conditional branch to an existing topic.
address-greptile-review — read every Greptile comment on your pull request and fix or reply on each one.

Writing a useful prompt

Tight inputs only. Codex is much better with constraints than with open-ended asks.

The issue number or the alarm constant you’re working on.
The file path or category to write into.
One or two existing topics to imitate.
The validation commands you want run before Codex stops.

Prompt template 1 — create a new topic

Create site/src/content/docs/topics/[category]/[slug].mdx for
alarm [ALARM_CONSTANT]. Imitate [similar-slug].mdx in the same
category.

Do not add owner fields or an Engineer Owner table.
Draft with the information available; do not invent missing details.
status: published. approvedForMx: null.
alarms: ["[ALARM_CONSTANT]"].

Run npm run build from site/ before stopping.

For a new guide, create a PR and always use Technical Contacts by System to find and manually assign the relevant FSE. The FSE completes the guide on the same branch and coordinates TW/SE2 review and merge. For an existing-guide edit, the author follows the current review process. See Guide ownership and workflow.

Audience and escalation context (paste at the end of template 1)

The template above gets the file in the right place with the right frontmatter. Paste the block below at the end of the same prompt to tell Codex who the topic is for and what’s off-limits on escalations.

Audience: a Maintenance Technician at the bench (or at the partner
site if the aircraft is still docked) reading the topic directly, AND
a Service Engineer reading it as a reference. Write steps that a
technician can carry out themselves where the failure mode permits;
when interpretation is genuinely required, use an escalation step
to route to the right on-call.

For any escalation, use a [[EscalationPath:<id>]] shortcode whose
id exists in site/src/data/escalation-paths.json. If the right
escalation path doesn't exist yet, stop and ask me.

Prompt template 2 — add a version-conditional branch

Open site/src/content/docs/topics/[category]/[slug].mdx.

Add a 2026.15+ branch. Keep the existing step path for versions
below 2026.15.

On the topic object, ensure softwareVersions: [...] includes 2026.15.
On each step that only applies to 2026.15+, add versions: ">=2026.15".
Valid versions are in site/src/data/version-manifest.

Run npm run build from site/.

Prompt template 3 — add an escalation step

Open site/src/content/docs/topics/[category]/[slug].mdx.

After step "[step-id]" add a terminal { type: "escalation" } step
with text: "[exact wording you want the technician to read]"
pointing to [[EscalationPath:[path-id]]].

Confirm [path-id] exists in site/src/data/escalation-paths.json.
If it doesn't, stop and ask.

Use this prompt when a topic’s rendered troubleshooting flow sends the reader back upward to an earlier box. The goal is to preserve the same troubleshooting logic while making the visible path move top-to-bottom.

Refactor only this topic's `topic.steps` array to fix backward navigation in the troubleshooting UI.

Problem:
The UI reveals troubleshooting steps based on their order in `topic.steps`. Some paths currently jump backward to a step that appears earlier in the array. Replace this sentence with a concrete example from the topic you are fixing, such as: "After the user clicks **Continue** on Step X, the UI highlights Step Y above the current location." This is confusing because users should never need to look above their current position for the next step.

Goal:
Ensure every normal user path progresses downward/top-to-bottom in the UI. Whenever the user clicks **Continue**, **Yes**, or **No**, the next displayed step must appear below the box they just clicked from.

Important:
Do not change the troubleshooting logic, technical behavior, outcomes, links, metadata, or external references. The same user choices must still lead to the same troubleshooting intent and final outcomes. Only restructure the step array and references as needed to improve the visual flow.

Approach:
1. Inspect this topic's `topic.steps` array.
2. Identify any `next` or `options[].next` references that point backward to an earlier step.
3. For each backward jump, determine whether the target step is being reused by multiple paths.
4. If a shared/reused step causes backward navigation, duplicate or restate that step later in the array near the path that needs it.
5. Give each duplicated step a unique, descriptive ID.
6. Update only the source path that jumps backward so it points to the new local duplicate step instead.
7. Preserve the existing wording wherever possible. Make only small wording changes if required for clarity.
8. Do not edit other topics.

Rules:
- Normal troubleshooting paths must always move forward/downward through the UI.
- Do not point a user back to an earlier step.
- Shared actions, checks, or tests may be duplicated to preserve linear flow.
- Repeated tests should be restated locally when needed.
- Any retry or retest must have a clear stopping condition or defined next step.
- Every path should end in a terminal outcome such as resolved, replace, return to service, contact support, or escalate.
- Do not create duplicate step IDs.
- Do not leave broken `next` or `options[].next` references.
- Do not introduce loops unless the existing logic explicitly requires them and they have a clear stopping condition.
- When possible, arrange steps so that all `next` references point to steps that appear later in the `topic.steps` array.

After editing:
1. Verify every `next` reference points to an existing step ID.
2. Verify every `options[].next` reference points to an existing step ID.
3. Verify all step IDs are unique.
4. Verify normal user paths progress forward in `topic.steps` order.
5. Run the repo's validation, lint, typecheck, or build command if available.
6. Summarize the changes made, including any duplicated steps and validation results.

Technical judgment

Codex drafts; people verify the technical content. Initiators provide accurate initial information; assigned FSEs complete new guides and coordinate expert input. Authors remain responsible for proposed changes to existing guides.

Safety and escalation
- Safety wording. A line like “Stop flying the aircraft” stays that way. If Codex softens it, you push back.
- Escalation targets. Codex picks an [[EscalationPath:<id>]] from the list. If the right id doesn’t exist, you create one — Codex doesn’t make one up.
Alarms and coverage
- Alarm constants. Alarm names live in ~/github/FlightSystems and are safety-relevant. Codex doesn’t rename or alias them.
- Failure-mode coverage. Whether every failure mode on the part you own has a distinct, actionable alarm with a topic is still your call.