Agent Prompt Patterns

# Agent Registry (in AGENTS.md)

## daily-digest
- **Consumers:** Sam (morning briefing), weekly-report agent (aggregation)
- **Deletion impact:** Sam loses morning summary, weekly-report loses daily inputs
- **Verdict:** KEEP

## inbox-sorter
- **Consumers:** None identified
- **Deletion impact:** Unknown
- **Verdict:** CANDIDATE FOR REMOVAL — validate or kill within 7 days

# BAD: No consumer, no deletion impact
## sentiment-tracker
Monitors social media sentiment about our brand.
Runs daily. Outputs to sentiment-log.md.

# GOOD: Named consumer, clear dependency
## sentiment-tracker
Monitors social media sentiment for weekly-report.
Consumer: weekly-report agent (pulls sentiment delta for executive summary)
Deletion impact: weekly-report loses sentiment section; Sam must manually check socials
Format: JSON with {platform, score_delta, top_mentions[3]}

STATUS UPDATE FORMAT:
- "Started X" → must include: PID, command, or file path
- "Completed X" → must include: output snippet, file path, or URL
- "Failed X" → must include: error message, what was tried
- "Skipped X" → must include: reason with evidence

# BAD: No proof
✅ Backed up database
✅ Sent daily digest email
✅ Rotated API keys

# GOOD: Every claim has evidence
✅ Backed up database → /backups/2026-03-15-db.sql.gz (43MB, sha256: a1b2c3...)
✅ Sent daily digest → Message-ID: <abc123@mail.example.com>, 3 recipients
✅ Rotated API keys → new key fingerprint: sk-...x4f2, old key revoked at 14:32 UTC

# In a script gate or agent wrapper:
run_with_proof() {
  local task="$1"
  shift
  local output
  output=$("$@" 2>&1)
  local exit_code=$?

  if [ $exit_code -eq 0 ]; then
    echo "DONE: $task | proof: $(echo "$output" | tail -3)"
  else
    echo "FAIL: $task | exit=$exit_code | error: $(echo "$output" | tail -5)"
  fi
  return $exit_code
}

# Usage:
run_with_proof "database backup" pg_dump -Fc mydb -f /backups/latest.dump

## Proof-of-Work (AGENTS.md entry)

NEVER say "done" without evidence. For every completed action, include at least one of:
- File path of output produced
- PID of process started
- URL of resource created/modified
- Command output (truncated to last 5 lines)
- Screenshot or hash of artifact

If you cannot produce proof, say "ATTEMPTED but cannot verify" and explain why.

Step 1: Produce output A
Step 2: Validate A meets spec → if invalid, return to Step 1 with fix instructions
Step 3: Use validated A to produce B
Step 4: Validate B meets spec → if invalid, return to Step 3 with fix instructions
...

## Newsletter Pipeline (cascading validation)

### Step 1: Research
- Output: research-notes.md
- Validation: must contain ≥ 3 sources, each with URL and date
- Failure: "Research incomplete — need 3+ sourced items. Currently have {n}. Add more."

### Step 2: Draft
- Input: validated research-notes.md
- Pre-check: verify research-notes.md passes Step 1 validation (don't trust upstream)
- Output: draft.md
- Validation: 400-800 words, includes all research items, no placeholder text
- Failure: "Draft {issue}. Fix and resubmit. Do not proceed to editing."

### Step 3: Edit
- Input: validated draft.md
- Pre-check: verify draft.md passes Step 2 validation
- Output: final.md
- Validation: grammar check passes, links resolve, formatting correct
- Failure: "Edit issues found: {list}. Return to editing. Do not publish."

### Step 4: Publish
- Input: validated final.md
- Pre-check: verify final.md passes Step 3 validation
- Gate: HUMAN APPROVAL REQUIRED before publish

def cascading_step(input_path, input_validator, processor, output_validator, max_retries=3):
    """Each step validates its input AND its output."""
    # Validate input (don't trust upstream)
    input_valid, input_errors = input_validator(input_path)
    if not input_valid:
        return {"status": "BLOCKED", "reason": f"Input validation failed: {input_errors}"}

    for attempt in range(max_retries):
        output = processor(input_path)
        output_valid, output_errors = output_validator(output)
        if output_valid:
            return {"status": "DONE", "output": output, "attempts": attempt + 1}
        # Loop back with fix instructions
        processor = make_fix_processor(processor, output_errors)

    return {"status": "FAILED", "reason": f"Failed after {max_retries} attempts", "last_errors": output_errors}

## Advisory Mode Configuration (AGENTS.md)

### Tier: Low (auto-approve after 3-day probation)
- Read any file in workspace
- Search codebase
- Generate summaries to memory files
- Run read-only API calls

### Tier: Medium (human approves after 2-week probation)
- Create/edit files in workspace
- Run test suites
- Generate reports
- Schedule cron jobs (read-only actions only)

### Tier: High (2-week probation, never fully autonomous)
- Git commit and push
- Create pull requests
- Post to Slack channels
- Modify cron jobs

### Tier: Restricted (always draft-only, human executes)
- Send email from user's account
- Delete files/data outside workspace
- Financial transactions (invoice, payment)
- Modify access controls or permissions
- Post to social media as user

## Probation Rules

1. New capability starts at its tier's probation period
2. During probation: agent proposes action, human approves/denies
3. Clean streak = no denials or corrections for full probation period
4. After clean streak:
   - Low: auto-promotes, agent logs the promotion
   - Medium: agent requests promotion, human approves
   - High: agent requests promotion, human approves, but spot-checks continue
   - Restricted: never promotes — always draft-only
5. Any denial during probation resets the probation clock
6. Graduated capability can be demoted if quality degrades

## Completion Contract: {workflow name}

### Done Criteria (all must be true)
- [ ] {criterion 1} — verified by: {method}
- [ ] {criterion 2} — verified by: {method}
- [ ] {criterion 3} — verified by: {method}

### Evidence Required
- {artifact 1}: {location/format}
- {artifact 2}: {location/format}

### Approval Stages
1. Automated validation passes (criteria above)
2. Agent self-review (checklist)
3. Human approval (if tier requires it)

### Timeout
- Maximum duration: {time}
- On timeout: {action — alert human, retry once, abort}
- Escalation: {who gets notified}

### Rollback
- Revert procedure: {steps}
- Rollback trigger: {conditions}

## Completion Contract: Production Deploy

### Done Criteria
- [ ] All tests pass on deploy branch — verified by: CI green check
- [ ] Docker image builds successfully — verified by: image SHA in registry
- [ ] Health check returns 200 — verified by: curl to /health within 60s
- [ ] No error spike in first 5 minutes — verified by: error rate < 0.1%

### Evidence Required
- CI run URL with green status
- Docker image SHA256
- Health check response (timestamp + status code)
- Error rate dashboard screenshot at T+5min

### Approval Stages
1. CI passes automatically
2. Agent verifies health check and error rate
3. Human confirms "deploy complete" in Slack

### Timeout
- Maximum duration: 15 minutes from deploy start
- On timeout: auto-rollback to previous version, alert #ops channel
- Escalation: page on-call engineer if rollback also fails

### Rollback
- Revert: deploy previous Docker image SHA
- Trigger: health check fails OR error rate > 0.5% OR human says "rollback"

Produce (Sonnet) → Review (Sam) → Cross-check (GPT) → Incorporate → Deliver

## Cross-Validation Protocol

### Step 1: Produce (Primary Model)
- Model: Claude Sonnet (fast, cost-effective for drafts)
- Output: first draft with citations

### Step 2: Review (Human)
- Reviewer: Sam
- Focus: factual accuracy, tone, strategic alignment
- Output: annotated draft with corrections

### Step 3: Cross-Check (Secondary Model)
- Model: GPT-4 or different Claude variant
- Prompt: "Review this document for factual errors, logical inconsistencies,
  and unsupported claims. Do not rewrite — only flag issues with explanations."
- Focus: catch blind spots the primary model and human missed
- Output: issue list with severity ratings

### Step 4: Incorporate
- Primary model incorporates human + cross-check feedback
- Changes tracked and justified

### Step 5: Deliver
- Final version with revision history
- Confidence rating based on number of issues found and fixed