Phase 8: Prompt Engineering

System prompt design principles

• Start minimal, add targeted instructions only when eval data shows failure (Right Altitude Framework)
• Every token must earn its place; reasoning degrades around ~3,000 prompt tokens
• Use three-tier boundary system: always do / ask-first / never do
• Reframe negatives as positive directives; reserve "never" for genuine safety constraints
• Include concrete code examples, not prose descriptions of code style

Positive framing — rewrite EVERY restriction as a directive

Every constraint that can be expressed as an action the agent should take must be written that way. The ONLY negative-framed lines that may appear in the final prompt are inside the "Never Do" tier of the three-tier permission structure (safety-critical only — typically ≤3 items).

Apply this rewrite pass once after the first draft, before shipping the prompt.

Just-in-time steering — inject guidance at decision points

Don't front-load every instruction in the system prompt. Instead, inject contextual guidance immediately before the relevant decision or tool call. Achieves 100% accuracy across 600 runs vs. 82.5% for upfront-only instructions.

When the deliverable includes system-prompt.md, prompt-architecture.md, or another prompt architecture artifact, include a visible ## Just-in-Time Steering Protocol section. This section must say:

• The base system prompt contains only stable identity, permissions, output format, and safety boundaries.
• Decision-specific guidance is injected just before the relevant tool call, file edit, permission decision, verification step, or recovery step.
• The injected guidance is removed after that decision unless a failure requires one post-result hint on the next turn.

Use the words "just-in-time" or "contextual steering" explicitly, and include a small trigger table like this:

Implementation pattern — three layers:

1. System prompt — stable identity, three-tier permissions, output format. ~500-1500 tokens, never changes mid-session.
2. Pre-tool guidance — small (~50-150 token) blocks injected immediately before specific tool calls, conditional on context.
3. Post-result hints — micro-corrections after tool failures, injected into the next turn only.

Example — file-edit tool

[System prompt — always present]
You edit files using str_replace with absolute paths.

[Injected before any str_replace call when target_file > 500 lines]
This file is 1,247 lines. Include >=3 lines of context on each side
of your old_string to guarantee uniqueness. If your match fails,
re-read the relevant region before retrying.

[Injected after a failed str_replace]
Your previous str_replace failed: old_string was not unique.
Add more surrounding context and retry once before considering
a different edit strategy.

The system prompt stays minimal. The just-in-time blocks fire only when relevant — so the prompt the agent sees at each decision point is laser-targeted.

Prompt architecture by task type

Specification granularity — what to specify vs. leave implicit

When producing a ready-to-use system prompt, include a compact ## Conditional Rules section with explicit branches. Use if / then / otherwise wording, not implicit prose. Include at least three rules covering permission decisions, large-file edits, verification, or recovery:

## Conditional Rules

- If a target file is larger than 500 lines, then edit with exact string
  replacement and at least 3 lines of context; otherwise use the standard edit
  path.
- If a change touches an ask-first path, then request approval before writing;
  otherwise proceed within the Always Do permissions.
- If verification fails, then preserve the error verbatim, identify root cause,
  and retry once; otherwise summarize the passing check count only.

Code style guidance requires concrete code blocks

When the system prompt specifies code style, include 2-3 verbatim code blocks showing the desired style. Prose descriptions ("use modern idioms", "keep functions short") produce inconsistent results because models infer different styles from the same words. A code block is unambiguous.

Include code blocks for: naming conventions, error-handling pattern, async/concurrency pattern, module/file structure, comment style. Even one well-chosen example anchors the model better than 10 lines of prose.

# In your produced system-prompt.md, include sections like:

## Code style

Use type hints on every public function. Prefer explicit returns
over implicit None. Use f-strings for formatting.

# Example of the style we expect:

def parse_config(path: Path) -> Config:
    """Load a Config from a YAML file."""
    if not path.exists():
        raise FileNotFoundError(f"Config not found at {path}")
    raw = yaml.safe_load(path.read_text())
    return Config.model_validate(raw)

The actual code blocks become part of the system prompt — the agent sees them at every step. Always include at least two examples covering different aspects of the style.

Evaluator prompts deserve equal investment — and aspirational framing

The evaluator's opening line activates a quality register that propagates through the entire evaluation. Utilitarian openers ("Check the work for issues") produce permissive, surface-level reviews. Aspirational openers produce rigorous, standards-driven reviews.

Open every evaluator prompt with at least one of these aspirational phrases (or equivalents in your domain):

• "You are an expert {domain} reviewer..."
• "Evaluate against the standard of an exceptional {profession}..."
• "Score against the highest standard of {quality dimension}..."
• "Review with the rigor of a museum-quality assessment..."

Verbatim example evaluator opener (use as a template, swap the domain):

You are an expert code migration reviewer with the standards of a museum
curator examining a Renaissance painting — every fragment must earn its
place on the wall. The migration you are evaluating must be:

- idiomatically modern (no remnants of the legacy style)
- conceptually clean (avoid AI slop, copy-paste cargo cult, defensive
  pseudo-coverage)
- worthy of a senior engineer's signature on the PR

Score the migration against the rubric below. For each criterion, cite
the specific lines or patterns that earn or fail the score.

Two stylistic levers in that example: (1) aspirational phrases like "expert", "exceptional", "highest standard", "museum-quality" — these activate the quality register; (2) anti-pattern callouts like "AI slop", "cargo cult", "defensive pseudo-coverage" — these steer more effectively than positive-only instructions because they name the failure modes directly.

Always include both registers in the evaluator opener — aspirational ceiling + anti-pattern floor.