| name | report-writing |
| description | Enforce rigor in technical analysis reports intended for another AI to consume — show raw data before interpretation, define domain terms with contrasting examples, prevent jargon and hallucination. Use when producing data-analysis reports or research summaries with quantitative claims. |
Report Writing Skill
When to use / when not to use
Use this skill when producing an analysis report intended for another
AI to consume — i.e. data extraction and interpretation, with every
quantitative claim backed by emitted raw output.
Do not use this skill for the three peer agents (code-reviewer,
refactoring-enforcer, qa-test-planner). Their output formats are
prescribed in their own system prompts and include fixes/suggestions,
which this skill explicitly forbids. No current agent invokes this skill;
it exists for future AI-to-AI analysis workflows.
Purpose
Ensure technical reports use precise, well-defined terminology with concrete examples. Prevent jargon without definitions, vague concepts, and reader confusion. This is a report to communicate findings to another AI for analysis, it should never discuss code solutions, propose architectures, or give estimates. It's data analysis, and interpretation alone, not a development plan.
Core Rules
RULE 0: Show raw data, never summarize from memory
Critical principle: Reports must be completely accurate. Every quantitative claim must be backed by emitted raw data.
Required workflow:
- Run extraction query - Generate actual data (SQL query, function call, script)
- Emit raw output - Include in report (table, code block, or appendix)
- Interpret from visible data - Only after data is visible
- NEVER summarize from memory - If data isn't shown, you're guessing
Example - BAD (hallucination risk):
We found 11 distinct page skeletons across certificate types.
Example - GOOD (verifiable):
We found 11 distinct page skeletons:
| Hash | Pages | Cert Types | Count |
| ------- | ------------------------------- | ---------- | ----- |
| a7f8... | [Commodity, Purpose, Transport] | CED, CVEDP | 2,500 |
| b2c9... | [Commodity, Purpose] | CVEDA | 89 |
...
(See "Data Extraction Query" below for verification)
For every quantitative finding:
RULE 1: Define all domain-specific terms on first use
Domain-specific terms include:
- Compound technical nouns (e.g., "page skeleton", "fingerprint level", "redundancy factor")
- Invented metrics or measurements
- Process-specific concepts (e.g., "deduplication", "clustering threshold")
- Any term that doesn't have a standard industry definition
Where to define:
- In a "Terminology" or "Definitions" section near the start of each analysis
- Before the term is used in results/analysis sections
RULE 2: Use the definition template
Every term definition MUST include:
**[Term Name]**
**What it is:** [One sentence describing the concept]
**How it's computed/identified:** [Specific formula, algorithm, or process. Include which fields/data are used]
**What uniqueness/variation means:** [Interpretation - what does it mean when two things have the same/different values?]
**Examples (minimum 2, must be different):**
1. [Concrete example 1 with actual data]
2. [Concrete example 2 with different characteristics to show contrast]
RULE 3: Examples must demonstrate contrast
The two examples should show:
- Different values/outcomes
- Edge cases or common cases
- What makes them similar vs different
Bad examples (too similar):
- Example 1: Config A has pages [Commodity, Purpose]
- Example 2: Config B has pages [Transport, Destination]
Good examples (show contrast):
- Example 1: Config A with pages [Commodity, Purpose, Transport] and Config B with [Transport, Purpose, Commodity] have identical page skeletons (same pages, different order)
- Example 2: Config C with pages [Commodity, Purpose] and Config D with [Commodity, Purpose, Transport] have different page skeletons (different page sets)
RULE 4: First draft validation checklist
Before completing a report section, verify:
Common Anti-Patterns to Avoid
❌ Anti-Pattern 1: Using jargon without definition
We found 11 distinct page skeletons across 3,254 configs.
✅ Correct Pattern: Define before use
## Terminology
**Page Skeleton:** [full definition with 2 examples]
## Results
We found 11 distinct page skeletons across 3,254 configs.
❌ Anti-Pattern 2: Circular definition
**Page Skeleton:** A skeleton of the pages in a configuration
✅ Correct Pattern: Operational definition
**Page Skeleton:** A deterministic hash representing the unique set of pages in a configuration, computed from the SHA-256 hash of alphabetically-sorted page names.
❌ Anti-Pattern 3: Single or identical examples
Examples:
1. Config A: [Commodity, Purpose, Transport]
2. Config B: [Commodity, Purpose, Transport]
✅ Correct Pattern: Contrasting examples
Examples:
1. Configs A and B both have pages [Commodity, Purpose, Transport] → **same skeleton** (order-independent)
2. Config C has pages [Commodity, Purpose] → **different skeleton** (missing Transport page)
Usage in Report Generation
Step 1: Draft with placeholders
On first pass, mark undefined terms:
We found 11 distinct {{DEFINE: page skeletons}}.
Redundancy factor is {{DEFINE: redundancy factor}}.
Step 2: Create Terminology section
Add definitions section before Results:
## Terminology
**Page Skeleton**
[Complete definition with 2 examples]
**Redundancy Factor**
[Complete definition with 2 examples]
Step 3: Validate
- Search report for undefined technical terms
- Check each definition has 2+ examples
- Verify examples show contrast
When to Use This Skill
Always use for:
- Technical analysis reports
- Documentation introducing new concepts
- Reports for cross-functional audiences (not just developers)
Can skip for:
- Internal code comments (audience familiar with codebase)
- Quick status updates
- Reports that only use standard industry terms (e.g., "database", "API", "authentication")
Enforcement
After generating a report section:
- Explicitly state: "Checking report against report-writing skill..."
- List terms that need definition
- Add Terminology section with all definitions
- Validate each definition has 2+ contrasting examples
- Mark as complete only after validation passes
