AI Field Guide Resources

Work With AI — Five-Part Brief

# Five-Part Brief

Outcome:
What useful result should this achieve?

Situation:
What circumstances materially change the answer?

Material:
What input, draft, data or source should AI work from?

Boundaries:
What must it avoid, preserve, not assume or stay within?

Deliverable:
What exactly should come back?

Optional acceptance criteria:
What would make the output usable enough to keep?

Rule: fill only the fields that remove meaningful ambiguity. If the missing problem is factual reality rather than instruction, move to Context Engineering.

Work With AI — Prompt experiment

# Prompt experiment

## Task
What real work am I trying to complete?

## Baseline instruction
...

## Observed defect
...

## Hypothesis
Which instruction change should reduce that defect?

## Change
Change one important variable where practical.

## Evidence
- defect reduced?
- new defect introduced?
- rework changed?
- acceptance criteria met?

## Conclusion
Keep / revise / discard this change.

Work With AI — Source-of-truth map

| Source | Owner / authority | Effective date | Scope | Superseded by | Use for |
|---|---|---|---|---|---|
| | | | | | |

Conflict rule:
1.
2.
3.

Known unknowns:
-

Work With AI — Context pack

# Context pack

Task:
Facts required:
Authoritative material:
Useful examples:
Explicit unknowns:
Do not assume:
Valid until / effective period:

Give AI Work — Minimal Harness starter

# AGENTS.md

## Mission
What this repository/system does and who it serves.

## Start here
1. Run: ./scripts/agent-init.sh
2. Read current work: docs/working/NEXT.md
3. Read architecture when relevant.

## Non-negotiables
- Do not change ...
- Preserve ...
- Never mark work complete without evidence.

## Verification
- Fast check:
- Focused check:
- End-to-end check:

## Tool / authority boundaries
- May:
- May not:
- Requires approval:

## End of session
- Update durable state.
- Record verification evidence.
- Record blockers/unknowns.
- Leave a next best action.

Durable task item

{
  "id": "F001",
  "priority": 1,
  "behavior": "Describe the observable outcome",
  "state": "not_started",
  "verification": ["Describe an observable or executable check"],
  "evidence": [],
  "blocked_reason": null,
  "next_action": null
}

Session handoff

# Verified now
- What works:
- Verification actually run:
- Evidence:

# Changed this session
-

# Broken / unverified
-

# Next best action
- Next item:
- Why:
- What counts as passing:
- What must not change:

# Commands
- Start:
- Verify:
- Debug:

Give AI Work — Loop contract

# Loop contract

Responsibility:
Trigger:
Type: finite goal / schedule / event / queue

State:
Goal / allowed work:
Verification:

Continue only if:
Stop:
Escalate:

Retry / repair:
- max attempts:
- what must change before retry:
- terminal state:

Budget:
- time:
- cost/token:
- human review:

Authority:
- may:
- may not:
- requires approval:

Retry / recovery record

# Failure
What failed?

# Evidence
What do we actually know?

# What changed before retry?
- input:
- state:
- strategy:
- tool/environment:

# Remaining budget
...

# If this fails again
repair / alternate path / rollback / compensate / escalate / stop

Run AI — Graph decision

# Do we need a graph?

Current workflow:

Signals:
[ ] meaningful branching/backtracking
[ ] resumable intermediate state
[ ] independently useful responsibilities
[ ] independently verifiable nodes
[ ] recovery/rollback paths
[ ] human authority gates
[ ] parallel work + reconciliation
[ ] coordination benefit exceeds orchestration cost

Simpler alternative considered:
script / workflow / single loop / deterministic service

Decision:
Graph / no graph / not yet

Reason:

Node contract

# Node contract

Name:
Responsibility:
Required shared state:
Private context:
Allowed tools / authority:
May not:
Output schema:
Success:
Failure / blocked output:
Side effects:
Retry policy:

Anchor / global objective

# System outcome
What real-world outcome should improve?

# External anchors
Evidence the graph cannot redefine for itself:
-

# Local metrics allowed to move
-

# Protected / frozen metrics
-

# Known conflicts
Which local optimization could harm the system outcome?

# Owner
Who is accountable for the global outcome?

Evidence labels

Back to AI Field Guide →