# AI Coding Workflow Audit Sample

This is a sanitized sample of the handoff format for a focused AI coding workflow / agent ops audit.
It is not a client deliverable and does not contain private repository data.

## Input

- Target: repository using an AI coding assistant for recurring implementation tasks
- Reported issue: the assistant repeats fixes, edits unrelated files, misses validation, and loses project context across sessions
- Available material: `AGENTS.md`, task prompt history, failing command output, package scripts, README, and a representative issue

## Audit Pass

1. Read the project instructions and identify conflicting rules.
2. Map the actual validation commands against the commands the assistant is told to run.
3. Check whether the task prompt includes clear scope, success criteria, and file ownership.
4. Inspect recent failed attempts for repeated error patterns.
5. Rewrite the operating instructions into a shorter execution path.

## Findings

The workflow has three avoidable failure modes:

- the instruction file mixes strategy, product notes, and mandatory execution rules without priority;
- the assistant is told to "validate thoroughly" but no exact smoke command is listed near the task;
- handoff notes describe what changed, but not what remains risky or unverified.

## Recommended Fix

Create a short agent runbook with four sections:

1. Scope boundaries: files and behaviors the assistant can change.
2. Validation gates: exact commands or browser checks that must pass.
3. Escalation triggers: login, payment, secrets, destructive changes, legal/account actions.
4. Handoff format: changed files, checks run, failed checks, residual risk, and next action.

## Example Patch Shape

```text
AGENTS.md
- Move mandatory rules to the top.
- Replace generic "test everything" wording with exact commands.
- Add "do not edit these files" when scope is narrow.
- Add a short final-report template.

task-template.md
- Current problem
- Expected result
- Allowed files
- Validation command
- Stop conditions
```

## Acceptance Check

Run one representative task after the instruction cleanup:

- the assistant identifies the allowed file scope before editing;
- the implementation avoids unrelated refactors;
- the required validation command is run or explicitly reported as blocked;
- the final handoff includes remaining risk instead of claiming full certainty.

## Handoff

Deliverables for a first pass:

- cleaned agent instruction file or suggested patch;
- one task template for future prompts;
- validation checklist matched to the repository;
- short report listing repeated failure modes and how to prevent them.

Remaining risk: the first audit improves the operating loop, but the strongest signal comes from running it against two or three real tasks and measuring whether repeated failure modes stop appearing.