| name | report-writing |
| description | Structure and write comprehensive research reports with proper citations. Use when finalizing research findings into a formal report. |
Report Writing Skill
This skill provides structured guidance for transforming research findings into well-organized, professional reports. It ensures consistency, clarity, and completeness across all research outputs.
When to Use This Skill
Invoke this skill when:
- Finalizing Research: Converting raw research notes and findings into a formal deliverable
- Creating Documentation: Producing technical documentation, white papers, or analysis reports
- Synthesizing Multiple Sources: Combining insights from various sub-agent research tasks into a unified narrative
- Stakeholder Communication: Preparing reports for executive review, technical teams, or external audiences
- Knowledge Preservation: Documenting research methodology and findings for future reference
Do NOT use this skill for:
- Quick summaries or informal notes (use simple markdown instead)
- Real-time status updates (use TODO lists)
- Raw data dumps (use structured data files)
Report Structure Template
Every research report MUST follow this hierarchical structure. Adapt section depth based on report complexity.
1. Executive Summary
Purpose: Provide a standalone overview for readers who may not read the full report.
Contents:
- Research objective (1-2 sentences)
- Key findings (3-5 bullet points)
- Primary recommendations or conclusions
- Critical limitations or caveats
Length: 150-300 words (1 page maximum)
Writing Tip: Write this section LAST, after all other sections are complete.
2. Introduction/Background
Purpose: Establish context and frame the research question.
Contents:
- Problem statement or research question
- Why this research matters (business/technical impact)
- Scope boundaries (what IS and IS NOT covered)
- Brief overview of approach taken
Length: 200-500 words
3. Methodology
Purpose: Enable reproducibility and establish credibility.
Contents:
- Data sources consulted (with dates accessed)
- Search strategies and queries used
- Selection criteria for sources
- Tools and techniques employed
- Limitations of the methodology
Example Format:
### Data Collection
- Primary sources: [List with access dates]
- Search queries: [Exact queries used]
- Time range: [Date boundaries for research]
### Analysis Approach
- [Describe analytical framework]
- [Note any tools or models used]
4. Findings
Purpose: Present discovered facts objectively, without interpretation.
Contents:
- Organized by theme, source type, or chronology
- Each finding clearly attributed to source
- Quantitative data in tables/charts when applicable
- Direct quotes for critical evidence
Structure Options:
- Thematic: Group by topic or category
- Comparative: Side-by-side analysis of alternatives
- Chronological: Timeline of developments
- Source-based: Organized by information source
5. Analysis
Purpose: Interpret findings and extract meaning.
Contents:
- Patterns and trends identified
- Contradictions or gaps in evidence
- Implications of findings
- Comparison with existing knowledge
- Confidence levels for conclusions
Analysis Framework:
### Pattern Analysis
[What recurring themes emerge?]
### Gap Analysis
[What questions remain unanswered?]
### Confidence Assessment
- High confidence: [Findings with strong evidence]
- Medium confidence: [Findings with partial evidence]
- Low confidence: [Tentative findings requiring validation]
6. Conclusions
Purpose: Synthesize analysis into actionable insights.
Contents:
- Direct answers to research questions
- Prioritized recommendations (if applicable)
- Suggested next steps or future research
- Final assessment of confidence
Format:
### Key Conclusions
1. [Most important conclusion]
2. [Second conclusion]
3. [Third conclusion]
### Recommendations
1. [Priority 1 action item]
2. [Priority 2 action item]
### Future Research Directions
- [Unanswered questions to explore]
7. References
Purpose: Enable verification and further exploration.
Contents:
- All sources cited in the report
- URLs with access dates
- Proper attribution for all quoted material
Citation Formatting Guidelines
In-Text Citations
Use numbered references in square brackets for inline citations:
Recent studies indicate a 40% improvement in efficiency [1]. This aligns with
earlier findings on automation benefits [2, 3].
For direct quotes, include page numbers or section identifiers:
According to the official documentation, "the system supports up to 10,000
concurrent connections" [4, Section 3.2].
Reference List Format
Use a consistent format for all references:
Web Sources:
[1] Author/Organization. "Article Title." Website Name. URL. Accessed: YYYY-MM-DD.
Academic Papers:
[2] Author(s). "Paper Title." Journal/Conference Name, Year. DOI/URL.
Documentation:
[3] "Document Title." Product Name Documentation, Version X.X. URL. Accessed: YYYY-MM-DD.
News Articles:
[4] Author. "Headline." Publication Name, Date Published. URL.
Citation Best Practices
- Always include access dates for web sources (content may change)
- Prefer primary sources over secondary reports
- Note version numbers for software documentation
- Archive volatile sources when possible (use archive.org links)
- Verify link validity before finalizing report
Writing Style Recommendations
Style Selection Guide
| Audience | Style | Characteristics |
|---|
| Executives | Executive | Concise, outcome-focused, minimal jargon |
| Technical Teams | Technical | Detailed, precise terminology, includes code/data |
| Academic/Research | Academic | Formal, extensive citations, methodological rigor |
| General Stakeholders | Balanced | Clear explanations, moderate detail, accessible |
Executive Style
Characteristics:
- Lead with conclusions and recommendations
- Use bullet points liberally
- Limit technical jargon; define necessary terms
- Focus on business impact and ROI
- Keep paragraphs short (3-4 sentences max)
Example:
## Key Finding: Cloud Migration Reduces Costs by 35%
**Bottom Line**: Migrating to cloud infrastructure will reduce operational
costs by $2.4M annually while improving system reliability.
**Recommended Action**: Approve Phase 1 migration by Q2 2025.
**Risk Level**: Low - Similar migrations have 94% success rate.
Technical Style
Characteristics:
- Include implementation details
- Use precise technical terminology
- Provide code samples, configurations, or specifications
- Document edge cases and limitations
- Include performance metrics and benchmarks
Example:
## Implementation: Rate Limiting Configuration
The API gateway implements token bucket rate limiting with the following
parameters:
| Parameter | Value | Rationale |
|-----------|-------|-----------|
| Bucket Size | 1000 | Handles burst traffic |
| Refill Rate | 100/sec | Sustainable throughput |
| Key Strategy | IP + User ID | Prevents abuse while supporting legitimate use |
```python
rate_limiter = TokenBucket(
capacity=1000,
refill_rate=100,
key_func=lambda req: f"{req.ip}:{req.user_id}"
)
### Academic Style
**Characteristics**:
- Formal third-person voice
- Extensive literature review
- Detailed methodology documentation
- Statistical rigor where applicable
- Acknowledge limitations explicitly
**Example**:
```markdown
## Literature Review
Previous research in automated code review systems has demonstrated
significant potential for defect detection. Smith et al. (2023) reported
a 23% reduction in production defects when implementing static analysis
tools [1]. However, Johnson and Lee (2024) note that these gains are
contingent upon proper configuration and team adoption [2].
The present study extends this work by examining the integration of
large language models into the review pipeline, an approach not
addressed in prior literature.
General Guidelines (All Styles)
- Active voice preferred: "The team implemented" not "It was implemented by the team"
- Specific over vague: "37% increase" not "significant increase"
- Present tense for findings: "The data shows" not "The data showed"
- Consistent terminology: Choose one term and use it throughout
- Avoid hedging excess: Limit "may," "might," "could possibly"
Quality Checklist Before Submission
Structure Verification
Content Quality
Citation Integrity
Writing Quality
Formatting
Final Review
Examples of Report Sections
Example: Executive Summary
## Executive Summary
This report evaluates three cloud database solutions for the customer
analytics platform migration: AWS Aurora, Google Cloud Spanner, and
Azure Cosmos DB.
**Key Findings**:
- AWS Aurora offers the lowest total cost of ownership ($145K/year)
- Google Cloud Spanner provides superior global consistency guarantees
- Azure Cosmos DB integrates best with existing Microsoft infrastructure
- All three solutions meet performance requirements (< 50ms p99 latency)
**Recommendation**: Proceed with AWS Aurora for Phase 1, with architecture
designed to allow future multi-cloud expansion.
**Timeline**: Implementation achievable within Q2 2025 with existing team.
**Confidence Level**: High - Based on proof-of-concept testing and vendor
consultations.
Example: Methodology Section
## Methodology
### Research Approach
This analysis employed a mixed-methods approach combining:
1. Vendor documentation review
2. Technical proof-of-concept testing
3. Industry analyst report analysis
4. Peer organization interviews
### Data Sources
| Source Type | Sources Consulted | Date Range |
|-------------|-------------------|------------|
| Vendor Docs | AWS, GCP, Azure official documentation | Dec 2024 |
| Analyst Reports | Gartner, Forrester database evaluations | 2024 |
| Technical Tests | Internal POC environment | Dec 15-22, 2024 |
| Interviews | 3 peer organizations (anonymized) | Dec 2024 |
### Evaluation Criteria
Solutions were evaluated against weighted criteria:
- Performance (30%): Latency, throughput, scalability
- Cost (25%): TCO over 3 years including migration
- Reliability (20%): SLA guarantees, disaster recovery
- Integration (15%): Compatibility with existing stack
- Vendor Support (10%): Documentation, support quality
### Limitations
- POC testing limited to 72-hour duration
- Cost projections based on current pricing (subject to change)
- Interview sample size limits generalizability
Example: Findings Section
## Findings
### Performance Comparison
All three solutions demonstrated acceptable performance for the target
workload of 10,000 queries per second:
| Solution | Avg Latency | P99 Latency | Max Throughput |
|----------|-------------|-------------|----------------|
| AWS Aurora | 12ms | 45ms | 15,000 QPS |
| Cloud Spanner | 15ms | 42ms | 18,000 QPS |
| Cosmos DB | 18ms | 48ms | 12,000 QPS |
*Source: Internal POC testing, December 2024 [1]*
### Cost Analysis
Three-year total cost of ownership analysis:
**AWS Aurora**: $435,000
- Compute: $180,000
- Storage: $95,000
- Data transfer: $85,000
- Support: $75,000
**Google Cloud Spanner**: $520,000
- [Detailed breakdown...]
**Azure Cosmos DB**: $485,000
- [Detailed breakdown...]
*Source: Vendor pricing calculators and enterprise discount estimates [2, 3, 4]*
Example: Analysis Section
## Analysis
### Cost-Performance Trade-offs
While AWS Aurora offers the lowest TCO, Cloud Spanner's 20% higher cost
delivers measurably better global consistency. For applications requiring
strong consistency across regions, this premium may be justified.
The cost difference primarily stems from:
1. Cloud Spanner's TrueTime infrastructure overhead
2. AWS Aurora's more aggressive reserved instance discounts
3. Different approaches to cross-region replication
### Risk Assessment
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| Vendor lock-in | High | Medium | Abstract data layer |
| Price increases | Medium | Medium | 3-year commitment |
| Service outage | Low | High | Multi-region deployment |
### Confidence Assessment
**High Confidence**:
- Performance meets requirements (validated via POC)
- AWS Aurora is most cost-effective option
**Medium Confidence**:
- 3-year cost projections (pricing may change)
- Integration complexity estimates
**Low Confidence**:
- Long-term vendor roadmap alignment
Example: References Section
## References
[1] Internal Engineering Team. "Database POC Test Results." Internal
Documentation. December 22, 2024.
[2] Amazon Web Services. "Amazon Aurora Pricing." AWS Documentation.
https://aws.amazon.com/aurora/pricing/. Accessed: December 20, 2024.
[3] Google Cloud. "Cloud Spanner Pricing." Google Cloud Documentation.
https://cloud.google.com/spanner/pricing. Accessed: December 20, 2024.
[4] Microsoft Azure. "Azure Cosmos DB Pricing." Azure Documentation.
https://azure.microsoft.com/pricing/details/cosmos-db/.
Accessed: December 20, 2024.
[5] Gartner. "Magic Quadrant for Cloud Database Management Systems."
Gartner Research, November 2024. (Subscription required)
[6] Smith, J. and Chen, L. "Comparative Analysis of Distributed Databases."
Proceedings of VLDB 2024. DOI: 10.14778/example.
Integration with Research Workflow
This skill integrates with the broader research workflow as follows:
Research Request → Data Collection → Analysis → [REPORT WRITING] → Verification → Delivery
↑
This Skill
Inputs Expected:
- Completed research findings (from sub-agents or direct research)
- Original research request/questions
- Source materials and citations
- Any constraints (length, audience, format)
Outputs Produced:
- Formatted report following structure template
- Complete reference list
- Executive summary for quick consumption
Quality Gates:
- Report must pass quality checklist before marking complete
- All citations must be verifiable
- Conclusions must trace back to evidence in findings
