zach-prompting

# Zach Prompting

## Goal

Produce the smallest justified revision that makes an instruction artifact easier for an agent to follow without weakening its outcome, evidence, safety, permission, output, or validation contract.

Treat brevity as a means, not the success metric. Call a change an improvement only when its behavior is verified on representative work.

## Select the mode

- **Review:** Inspect and report findings. Do not edit when the user asked only for assessment.
- **Rewrite:** Return the revised artifact or apply an in-scope edit when the user asked for a change.
- **Debug:** Use real failures or traces to find a likely instruction-level cause, then propose or make a surgical change.
- **Migrate:** Establish the current model, runtime, prompt, tools, reasoning or effort setting, and eval baseline. Change one variable group at a time.

Infer the mode from the request. Ask only when choosing incorrectly would cause an unauthorized edit or materially different result.

## Rewrite the contract

1. **Recover intent.** Read the whole target plus governing instructions. Identify the audience, runtime, model, request type, and the larger purpose the artifact serves.
2. **Map what must survive.** Record the user-visible outcome, success criteria, true invariants, evidence rules, authorization boundary, relevant tools, required output, validation, and stop conditions. Preserve explicit user values.
3. **Find behavioral friction.** Locate contradictions, repeated rules, obsolete scaffolding, behavior-neutral examples, irrelevant tools, vague tone labels, unneeded absolutes, keyword shortcuts, hidden approval rules, unsupported claims, and missing completion criteria.
4. **Make a narrow revision.** Lead with the outcome. Keep one rule per behavior. Use absolutes only for invariants; use decision rules for judgment. State safe autonomy and approval boundaries once. Add detail only where it changes behavior.
5. **Check the result.** Compare the revision against the preserved contract. Run available representative evals or validation. For consequential or complex changes, prefer a fresh-context verifier over self-critique.

Do not force a small prompt into a large template. For complex artifacts, use this order when it helps: context, goal, success criteria, constraints, tools, output, stop rules.

## Apply these editing rules

### Outcomes and completion

- Describe the destination and completion bar before prescribing process.
- Retain required calculations, evidence, citations, fields, and validation even when shortening.
- Define when to retry, use a fallback, ask for missing input, abstain, or finish.
- End autonomous work only when complete or blocked on input only the user can provide.

### Boundaries and autonomy

- Distinguish inspect/report requests from change/build requests.
- Permit safe, reversible, in-scope actions needed for an authorized change.
- Require a pause for destructive or irreversible actions, external writes not already authorized, purchases, real scope expansion, or user-only information.
- Keep research, design, implementation, review, and external coordination from silently bleeding into one another.
- Respect ownership and instruction hierarchy. For vendored, generated, protected, or out-of-scope artifacts, return a patch or bridge instead of modifying the source.

### Evidence and progress

- Define which claims need support and what sufficient evidence means.
- Treat missing evidence as unknown, not as proof of absence.
- Separate retrieved fact, user-provided fact, inference, and creative wording.
- Ground progress and completion claims in current tool results. Report failed, skipped, unverified, and completed checks plainly.
- Never invent names, dates, metrics, outcomes, capabilities, citations, or test results to strengthen an artifact.

### Tools and delegation

- Keep only task-relevant tools. State what each tool does, when to use it, important outputs, and meaningful failure behavior.
- Make prerequisites explicit. Parallelize independent reads; sequence dependent work; synthesize before acting.
- Use programmatic or batch tool calling only for bounded deterministic reduction. Keep approval, citations, semantic judgment, and final validation in direct model control.
- Delegate independent work when it improves speed or verification, but give each agent a bounded deliverable and enough source context to succeed.

### Reader-facing communication

- Define tone with observable choices instead of labels such as “friendly” or “professional.”
- Lead final responses with the outcome. Preserve material facts, decisions, caveats, and next actions; remove repetition and optional background first.
- Prefer clear sentences over fragments, jargon, or dense shorthand.
- Do not ask the model to expose, reproduce, or transcribe private chain-of-thought. Request conclusions, evidence, assumptions, and concise rationale instead.

## Keep vendor guidance conditional

Read `references/vendor-guidance.md` when the request names GPT-5.6, Claude Fable 5, model migration, reasoning or effort settings, long-run harness behavior, or source-backed rationale.

Do not copy model-specific settings into a general artifact unless the named runtime uses them. Prefer shared behavioral rules in portable skills and keep provider controls in scoped sections.

## Return the result

Match the requested mode and native artifact format. Include only what helps the user evaluate the change:

1. the revised artifact, applied diff, or review findings;
2. a compact change map: preserved, removed, clarified, and conditionalized;
3. unresolved conflicts or missing context;
4. validation performed and observable results; and
5. status: `validated`, `awaiting-evals`, `no-change-needed`, or `blocked`.

Do not claim `validated` without real checks. If no eval can run, label the revision `awaiting-evals` and provide the smallest representative test set with explicit pass conditions.