| name | writing-reports |
| description | Guides production of stakeholder-reviewable reports across coding, research, data analysis, and writing work. Use when producing any of these seven report types: (1) observation — peripheral finding for cold-start agent hand-off; (2) findings — data-first results briefing with tables, charts, and steering questions; (3) notice — lightweight improvement idea captured outside current task scope; (4) open-question — open question framing for fresh-agent delegation; (5) architecture — pre-implementation analysis with diagrams, contracts, and risk register; (6) test-definition — risk-driven test plan with test matrix and fixtures strategy; (7) knowledge-transfer — post-cycle retrospective covering wins, pain points, and next-cycle changes. Applies a model-first, no-code-dump contract: lead with diagrams and schemas, never include full implementations. Saves reports under __reports__/TOPIC/ using round-versioned naming.
|
Reporting Skill
Navigation
Read this table first. Pick the report type that matches your situation, then open the linked reference.
For complex multi-phase efforts surfaced during analysis, use the managing-roadmaps skill to produce a formal roadmap.
Core Contract
Model-first
Lead every report with diagrams, schemas, and contracts. Never open with raw code or data dumps.
No raw dumps
Reports must not include full implementations.
Allowed: signatures, schemas, pseudo-code, and small snippets strictly necessary to clarify a contract or invariant.
Stakeholder-reviewable
Prefer tables, diagrams, and short sections. Avoid enumerating exhaustive permutations; use equivalence classes, boundary sets, and consolidation.
File Locations and Naming
| Artifact type | Location |
|---|
| All reports (iterative) | __reports__/<topic>/ |
| Durable architectural decisions | __design__/ |
| Living implementation roadmaps | __roadmap__/<campaign>/ |
Naming pattern: __reports__/<topic>/<round>-<name>_v<version>.md
| Field | Format | Meaning |
|---|
<topic> | snake_case | Descriptive folder name for a work session |
<round> | 00, 01, 02 … | Two-digit counter, one per batch of report generation. All reports written in the same batch share the same value. The next batch uses max(existing prefixes) + 1; an empty topic starts at 00. Do not increment per report. |
<name> | snake_case | Describes the report |
<version> | v0, v1, v2 … | Increments per iteration of the same report |
Example:
__reports__/<topic>/
00-architecture_v0.md ┐
00-test_definition_v0.md ├─ batch 0: three reports written together
00-open_question_v0.md ┘
01-findings_v0.md batch 1: one report
02-test_definition_v1.md batch 2: revision of the v0 from batch 0
- Revisions: a report updated in a later batch is written as a new file at that batch's
<round> with <version> bumped (e.g. 00-foo_v0.md stays; revision is 02-foo_v1.md). Never overwrite or rename the original.
Auto-create: auto-create __reports__/<topic>/ if it does not exist.
README convention: each __reports__/<topic>/ should include a README.md listing documents grouped by <round> in chronological order, marking the latest versions, and providing a short status section.
