Aaalexy/craft-codex-prompts

Craft Codex Prompts

Objective

Turn incomplete context into a task package that another Codex conversation can execute without treating derived interpretation as fact. Optimize for source fidelity, bounded authority, testable completion, and low prompt overhead.

Select the operation

• Draft: Build a prompt from files, project context, or a rough request.
• Review: Diagnose weaknesses in an existing prompt, then produce a revised version.
• Handoff: Convert prior work, results, and open issues into the next executable prompt.
• Knowledge loop: Produce knowledge-base-ready current-state, decision, open-issue, and handoff updates.

If the user asks only for a prompt, return only the prompt plus essential assumptions. If they ask for a reusable workflow, return the full task package.

Workflow

1. Establish sources and authority

Inspect user-provided files and accessible project material read-only before drafting when doing so is authorized and useful. Do not modify the source project while merely preparing a prompt.

Classify inputs:

• Primary facts: current files, repository state, explicit user statements, authoritative project documents.
• Derived context: summaries, earlier assistant conclusions, reports, and copied chat.
• Unknowns: missing files, unverified runtime state, unresolved choices, and external dependencies.

Treat derived context as a lead, not proof. State explicitly that the executing conversation must verify it against primary sources.

Do not assume files attached to one conversation are available in another. Name every file or exact workspace the executing conversation must receive.

2. Identify task type

Choose the closest task type:

• answer or explain;
• inspect or review;
• diagnose;
• change or build;
• research or compare;
• create an artifact;
• perform an external action.

Preserve the matching authority boundary. A request to analyze or diagnose does not authorize edits. A request to change or build normally authorizes in-scope implementation and verification, but not unrelated refactors, publishing, messaging, commits, pushes, or destructive actions.

Read task-blueprints.md for the matching task pattern.

3. Separate stable rules from the task delta

Place durable project rules in a project contract such as AGENTS.md, PROJECT_BRIEF.md, or CODEX_TASK_CONTRACT.md. Keep the current prompt focused on what changed this time.

Repeat a stable rule in the task prompt only when it is safety-critical or likely to be missed.

4. Resolve ambiguity proportionally

Ask a clarifying question only when the answer would materially change scope, source selection, irreversible behavior, external effects, or the acceptance standard. Otherwise choose the safest reasonable assumption and label it.

Never hide a missing source, unsupported capability, or external blocker inside confident wording.

5. Compose the task package

Create these sections when relevant:

1. Outcome: one concrete end state.
2. Source of truth: exact files, paths, data, or user decisions.
3. Current state: only verified or clearly attributed facts.
4. Scope: allowed reads, edits, systems, and artifacts.
5. Non-goals: likely but unauthorized expansions.
6. Adjacent checks: downstream surfaces that can expose the same defect.
7. Execution guidance: constraints that affect correctness, not speculative implementation detail.
8. Acceptance: observable checks and expected evidence.
9. Blockers and stop conditions: conditions that require reporting instead of guessing.
10. Delivery: files changed, artifacts, evidence, limitations, and next handoff.

Use the L1-L4 verification ladder when implementation is involved:

• L1: syntax, import, schema, or static validation;
• L2: unit, service, or focused regression tests;
• L3: real-file or end-to-end data-path validation;
• L4: actual UI, packaged runtime, device, production-like, or human acceptance.

Do not present a lower level as proof of a higher level.

Include this source-fidelity clause, adapted to the task:

Treat this prompt as an execution brief, not as proof of repository state. Verify its claims against the current workspace and primary files. If they conflict, preserve the source material, report the conflict, and follow the primary source unless the user decides otherwise.

6. Keep the prompt executable

• Lead with the outcome.
• Use direct instructions and concrete nouns.
• Prefer filenames, paths, counts, and expected artifacts over adjectives.
• Avoid copying raw chat unless exact wording is itself evidence.
• Avoid prescribing architecture before inspection unless the user fixed that choice.
• Keep prohibitions limited to realistic failure modes.
• State whether Codex should only report, diagnose, implement, or implement and verify.
• End with a compact completion format.

7. Audit before delivery

Score the prompt internally against six checks:

• Fidelity: Can each factual claim be traced to a source?
• Authority: Are reads, edits, external actions, and prohibited actions unambiguous?
• Completeness: Are likely adjacent consumers and failure paths covered?
• Testability: Can completion be demonstrated with observable evidence?
• Feasibility: Are unavailable tools, runtime limits, and human dependencies exposed?
• Brevity: Does every instruction change execution or verification?

Return one status:

• READY: executable with available context;
• READY_WITH_ASSUMPTIONS: executable after listing bounded assumptions;
• NEEDS_INPUT: one or more material choices are missing;
• BLOCKED_SOURCE_MISSING: required primary material is unavailable.

Do not inflate the prompt merely to improve its apparent rigor.

8. Close the knowledge loop

When the user archives work in Obsidian or another knowledge base, read obsidian-loop.md. Keep immutable raw chats separate from current project truth. After execution, update current state, decisions, open issues, and the handoff instead of relying on the transcript alone.

Default output

Unless the user requests another format, return:

## TASK_BRIEF
[verified facts, assumptions, unknowns, sources]

## MAIN_PROMPT
[copy-ready prompt]

## PROMPT_STATUS
[READY, READY_WITH_ASSUMPTIONS, NEEDS_INPUT, or BLOCKED_SOURCE_MISSING]
[short explanation and any required attachments]

For prompt review, add a short KEY_GAPS section before MAIN_PROMPT. Do not expose private chain-of-thought; provide concise, decision-relevant reasons.