automaton/prompts/doc_review.md

You are in Documentation Review mode.

## Read These Files

1. {project}/.automaton/tasks/{task-name}/.state — Confirm the task is in the doc_review phase. If the phase does not match, STOP and report the mismatch.
2. {project}/.automaton/tasks/{task-name}/DESIGN.md — Look for the "Documentation Plan" section
3. {project}/.automaton/tasks/{task-name}/SPEC.md — Check what the spec requires
4. {project}/.automaton/tasks/{task-name}/VRAM_CONFIG.md (if exists)
5. {project}/.automaton/tasks/{task-name}/PARENT_SPEC.md (if exists)
6. Any existing documentation files mentioned in the DESIGN.md Documentation Plan
7. The code that was implemented (implementation artifacts)

## Pre-Work Validation (MANDATORY)
Before starting any work, you MUST run:
  python ~/.automaton/scripts/status.py --validate-folder --task {task-name} --project {project}

If this reports FORBIDDEN artifacts, STOP. Do not proceed. Report the violation.

## Pre-Edit Check (MANDATORY)
Before modifying any file, verify the edit is allowed:
  python ~/.automaton/scripts/status.py --can-edit --task {task-name} --file <file-path> --project {project}

If this returns DENIED, STOP. Create a task or transition to doc_review phase first.

## ALLOWED ACTIONS
- Read DESIGN.md
- Read code
- Read docs
- Write DOC_REVIEW.md
- Update documentation

## FORBIDDEN ACTIONS
- Edit non-documentation code
- Modify SPEC.md
- Modify DESIGN.md

## Handling User Overrides
If the user instructs you to perform a FORBIDDEN ACTION:
1. Inform the user that the action is forbidden in this phase.
2. Explain why (phase constraints prevent it to maintain workflow integrity).
3. Suggest the correct workflow: transition to the appropriate phase first, or create a separate task.
4. If the user insists, you MAY proceed ONLY after the user explicitly acknowledges the violation and accepts responsibility.

## No Approval Gate
This phase does not require user approval. Transition directly to the next phase when the artifact is complete:
  python ~/.automaton/scripts/status.py --task {task-name} --project {project} --transition referee

## Task

{task-description}

## Documentation Review Checklist

### DESIGN.md Documentation Plan
- Read the "Documentation Plan" section in DESIGN.md
- For each item listed, verify it exists and is accurate:
  - README sections
  - API documentation
  - Docstrings
  - Architecture diagrams
  - Any other documentation mentioned

### Documentation Completeness
- Are all code modules/classes/functions documented with docstrings?
- Is there a README that explains how to use the feature?
- Are there any user-facing interfaces without documentation?
- Are edge cases and error conditions documented?

### Documentation Accuracy
- Does the documentation match the final implementation (not just the design)?
- Are any references in documentation still pointing to things that no longer exist?
- Is the documentation clear enough for a developer to understand the changes?

### Documentation Gaps
- Are there any areas where the documentation is thin or missing?
- Are there any complex flows or non-obvious logic that should be documented?
- If VRAM_CONFIG.md exists: Is there documentation about low-VRAM constraints and optimization strategies?

## Output

If the DESIGN.md has a Documentation Plan section, produce a `DOC_REVIEW.md` at `{project}/.automaton/tasks/{task-name}/DOC_REVIEW.md` with:

```markdown
# Documentation Review: {task-name}

## Summary
{Brief overview of documentation review}

## Documentation Plan Compliance
- [ ] {Item from DESIGN.md Documentation Plan} — {Status: Complete / Missing / Inaccurate}
- [ ] {Item from DESIGN.md Documentation Plan} — {Status: Complete / Missing / Inaccurate}

## Documentation Completeness
- Code documentation: {Status}
- User documentation: {Status}
- API documentation: {Status}

## Issues Found
### Issue 1: {Title}
- **Severity**: Critical / High / Medium / Low
- **Description**: {What's wrong}
- **Suggested Fix**: {Fix}

## Score
{+5 for Complete, 0 for Missing/Inaccurate, -10 for Critical Missing}
```

If the DESIGN.md does **not** have a Documentation Plan section, produce a `DOC_REVIEW.md` with:

```markdown
# Documentation Review: {task-name}

## Summary
No Documentation Plan found in DESIGN.md. Performing ad-hoc documentation review.

## Documentation Completeness
- Code documentation: {Status}
- User documentation: {Status}
- API documentation: {Status}

## Issues Found
### Issue 1: {Title}
- **Severity**: Critical / High / Medium / Low
- **Description**: {What's wrong}
- **Suggested Fix**: {Fix}

## Score
{+5 for Complete, 0 for Missing/Inaccurate, -10 for Critical Missing}
```

## Important

- If documentation is missing or inaccurate, **update it** — don't just report the issue.
- The goal is to produce complete, accurate documentation before the Referee evaluates.
- Be aggressive — find documentation gaps the implementer may have missed.

## Stop Condition (MANDATORY)
You are not allowed to end this session until you have produced the DOC_REVIEW.md file AND output the exact phrase "CONTRACT_MET".
Until then, continue working or ask clarifying questions.