agent-notes

name	agent-notes
description	Write succinct agent notes to minimise context. Use when: reporting on work done, summarising completed tasks, reviewing another agent's output, flagging what was good, what needs fixing, what is incomplete. Triggers: report, summarise work, note findings, review agent output, what was good, what needs improving.
argument-hint	self-report | peer-review

Agent Notes

Write minimal, scannable notes. Every byte counts — other agents will read this.

When to Use

• Self-report: After completing a task, log what you did and any issues
• Peer-review: After reading another agent's output, score and flag it

Rules

• One bullet per item — no prose, no padding
• Max 5 bullets per section
• Omit sections that are empty
• No markdown headings inside bullets
• File path references use short relative paths

Procedure

Self-Report

1. Open (or create) .notes/agent-report.md
2. Append a block using self-report template
3. Replace {{DATE}} with today's date (ISO 8601: YYYY-MM-DD)
4. Replace {{AGENT_NAME}} with your agent name or filename (e.g. test-plan-writer)
5. Fill only non-empty sections; remove empty ones
6. Validate before saving: confirm date and agent are set — if either is {{...}}, replace before writing

Peer-Review

1. Read the target output (file or chat)
2. Open (or create) .notes/agent-report.md
3. Append a block using peer-review template
4. Replace {{DATE}} with today's date (ISO 8601: YYYY-MM-DD)
5. Replace {{AGENT_NAME}} with your agent name or filename
6. Replace {{REVIEWED_AGENT_OR_FILE}} with the name or path of what you reviewed
7. Fill only non-empty sections; remove empty ones
8. Validate before saving: confirm date, reviewer, and subject are set — if any is {{...}}, replace before writing

Decision Line (peer-review only)

Every peer-review block must end with a machine-scannable decision line in exactly this format:

DECISION: APPROVED | REQUIRES REVISION — <one-line reason>

Rules:

• Must be the last line of the block (after all bullets)
• Use APPROVED or REQUIRES REVISION — no other values
• The reason after — is required; never leave it blank
• Downstream agents scan for DECISION: APPROVED or DECISION: REQUIRES REVISION to gate their work

Output Format

Appended block in .notes/agent-report.md. Each block is self-contained and timestamped.

---

Writing Output Documents

This applies to all primary output files — design plans, review reports, and test reports. Verbose documents cost every downstream agent that reads them.

Rules

• Lead with the verdict or result — never bury it
• Tables over prose: decisions, findings, and results belong in rows, not paragraphs
• One item per table cell — no paragraph explanations inside cells
• Bullets over sentences, sentences over paragraphs
• No preamble ("This document describes…") and no conclusion ("In summary…")
• Omit empty sections entirely — do not write "Not applicable" or "N/A" paragraphs
• No repetition: if something was stated in the summary, do not restate it in the body

Format by document type

Design plan (*-design.md):

• Summary: 2–3 sentences only — what it does, why, who benefits
• 9-layer matrix: one decision per row, max 3 sentences per cell; no paragraph blocks
• Technical spec: flat bullet list; no sub-prose
• Acceptance criteria: table rows only; pass condition is one testable line

Review report (*-review.md):

• Verdict: one sentence — cite the single most important finding
• Verification table: one row per claim, result in one word (CONFIRMED / UNVERIFIED / INCORRECT)
• 9-layer scores: one key finding per layer, one sentence max
• Strengths / weaknesses: one bullet per item, no nested prose
• Recommendations table: recommendation is an imperative sentence; rationale is one phrase

Test report (*-test-report.md):

• Results: one table row per criterion; evidence in one line
• Failures: fill structured fields only; one line per field
• Summary: counts + one-line action required