agent-notes

Files (3)

• SKILL.md
• peer-review.md · templates/
• self-report.md · templates/

SKILL.md (first lines)

# 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](./templates/self-report.md)
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](./templates/peer-review.md)
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

From pedrogrande/adf, MIT.