research-reports

Research Reports Skill

This skill provides utilities for formatting and managing research reports generated by the stepwise-research plugin.

When to Use This Skill

Claude Code will automatically invoke this skill when:

• A research report needs standardized formatting
• YAML frontmatter needs to be generated for a report
• Bibliography formatting needs to be standardized
• Metadata needs to be extracted from research findings

Available Scripts

generate-report

Purpose: Generate a properly formatted research report with YAML frontmatter, citations, and structured sections.

Usage:

research/skills/research-reports/scripts/generate-report \
  --title "Research on [Topic]" \
  --query "Original research question" \
  --keywords "keyword1,keyword2,keyword3" \
  --agent-count N \
  --source-count M \
  --output-file "thoughts/shared/research/filename.md" \
  --executive-summary "Summary text" \
  --findings "Findings text with citations" \
  --conclusions "Conclusion text" \
  --bibliography "Bibliography entries"

Parameters:

• --title (required): Report title
• --query (required): Original research question
• --keywords (required): Comma-separated keywords
• --agent-count (required): Number of research agents spawned
• --source-count (required): Total unique sources cited
• --output-file (required): Output path (should be in thoughts/shared/research/)
• --executive-summary (optional): Executive summary section content
• --findings (optional): Detailed findings section content
• --conclusions (optional): Conclusions section content
• --bibliography (optional): Bibliography entries (numbered list)

Output: Generates a markdown file with this structure:

---
title: [Title]
date: YYYY-MM-DD
query: [Query]
keywords: [keywords]
status: complete
agent_count: N
source_count: M
---

# [Title]

## Executive Summary
[Content]

## Detailed Findings
[Content with citations]

## Conclusions
[Content]

## Bibliography
[Numbered citations]

---
*Research conducted by stepwise-research multi-agent system*
*Generated: [timestamp]*

Report Structure Standards

YAML Frontmatter Fields

• title: Human-readable report title
• date: ISO 8601 date (YYYY-MM-DD)
• query: Original research question (verbatim)
• keywords: 5-8 extracted key terms
• status: complete | draft | in-progress
• agent_count: Number of research agents used
• source_count: Total unique sources cited

Required Sections

1. Executive Summary: 3-5 sentence overview answering the research question
2. Detailed Findings: Organized by theme/topic with subsections
3. Conclusions: 3-5 bullet points summarizing key takeaways
4. Bibliography: Numbered list with format: [N] Source Title - URL

Optional Sections

• Cross-References and Contradictions: Areas of consensus/disagreement
• Methodology: How research was conducted (if relevant)
• Limitations: Gaps or constraints in the research

Citation Format

Citations must follow this format:

In-text:

Docker uses containerd as its default runtime [1] [2].

Bibliography:

[1] Docker Documentation - https://docs.docker.com/engine/
[2] Containerd Official Site - https://containerd.io/

Integration with Thoughts System

Reports are saved to:

thoughts/shared/research/[sanitized-topic]-[YYYY-MM-DD].md

Filename sanitization rules:

• Convert to lowercase
• Replace spaces with hyphens
• Remove special characters (keep only alphanumeric and hyphens)
• Truncate to 60 characters max
• Append date suffix

Example:

• Query: "What is Kubernetes and how does it work?"
• Filename: what-is-kubernetes-and-how-does-it-work-2026-02-19.md

After report creation, the thoughts-management Skill will automatically sync hardlinks to thoughts/searchable/.

Script Implementation Notes

The generate-report script:

• Validates all required parameters
• Generates properly formatted YAML frontmatter
• Ensures consistent section ordering
• Adds generation metadata footer
• Creates parent directories if needed
• Returns success/failure status

Error Handling

If report generation fails:

• Check that thoughts/shared/research/ directory exists
• Verify all required parameters are provided
• Check for write permissions
• Validate YAML frontmatter syntax

Future Enhancements

Potential future additions to this skill:

• validate-report: Check report structure and citation format
• export-report: Convert to PDF, HTML, or other formats
• merge-reports: Combine multiple research reports
• extract-citations: Pull bibliography from existing reports