[P4] Research Report Generator/Updater Utility

[jeremyeder]

Coldstart Implementation Prompt: Research Report Generator/Updater Utility

Priority: P4
Repository: agentready (https://github.com/redhat/agentready)
Branch Strategy: Create feature branch from main

---

Context

You are implementing a feature for AgentReady, a repository quality assessment tool for AI-assisted development.

Repository Structure

agentready/
├── src/agentready/          # Source code
│   ├── models/              # Data models
│   ├── services/            # Scanner orchestration
│   ├── assessors/           # Attribute assessments
│   ├── reporters/           # Report generation (HTML, Markdown, JSON)
│   ├── templates/           # Jinja2 templates
│   └── cli/                 # Click-based CLI
├── tests/                   # Test suite (unit + integration)
├── examples/                # Example reports
└── specs/                   # Feature specifications

Key Technologies

• Python 3.11+
• Click (CLI framework)
• Jinja2 (templating)
• Pytest (testing)
• Black, isort, ruff (code quality)

Development Workflow

1. Create feature branch: git checkout -b NNN-feature-name
2. Implement changes with tests
3. Run linters: black . && isort . && ruff check .
4. Run tests: pytest
5. Commit with conventional commits
6. Create PR to main

---

Feature Requirements

Research Report Generator/Updater Utility

Priority: P4 (Enhancement)

Description: Create a utility tool to help maintain and update the research report (agent-ready-codebase-attributes.md) following the validation schema defined in contracts/research-report-schema.md.

Requirements:

• Generate new research reports from templates
• Validate existing reports against schema (contracts/research-report-schema.md)
• Update/add attributes while maintaining schema compliance
• Automatically format citations and references
• Extract tier assignments and metadata
• Verify 25 attributes, 4 tiers, 20+ references
• Check for required sections (Definition, Measurable Criteria, Impact on Agent Behavior)

Use Case:

# Validate existing research report
agentready research validate agent-ready-codebase-attributes.md

# Generate new research report from template
agentready research init --output new-research.md

# Add new attribute to research report
agentready research add-attribute \
  --id "attribute_26" \
  --name "New Attribute" \
  --tier 2 \
  --file research.md

# Update metadata (version, date)
agentready research bump-version --type minor

# Lint and format research report
agentready research format research.md

Features:

• Schema validation (errors vs warnings per research-report-schema.md)
• Automated metadata header generation (version, date in YAML frontmatter)
• Attribute numbering consistency checks (1.1, 1.2, ..., 15.1)
• Citation deduplication and formatting
• Tier distribution balance warnings
• Category coverage analysis
• Markdown formatting enforcement (consistent structure)
• Reference URL reachability checks

Related: Research report maintenance, schema compliance, documentation quality

Notes:

• Must follow contracts/research-report-schema.md validation rules
• Should prevent invalid reports from being committed
• Could integrate with pre-commit hooks for research report changes
• Consider CLI commands under agentready research subcommand
• Tool should be self-documenting (help users fix validation errors)
• Future: Could use LLMs to help generate attribute descriptions from academic papers

---

---

Implementation Checklist

Before you begin:

• Read CLAUDE.md for project context
• Review existing similar features (if applicable)
• Understand the data model (src/agentready/models/)
• Check acceptance criteria in feature description

Implementation steps:

• Create feature branch
• Implement core functionality
• Add unit tests (target >80% coverage)
• Add integration tests (if applicable)
• Run linters and fix any issues
• Update documentation (README.md, CLAUDE.md if needed)
• Self-test the feature end-to-end
• Create PR with descriptive title and body

Code quality requirements:

• All code formatted with black (88 char lines)
• Imports sorted with isort
• No ruff violations
• All tests passing
• Type hints where appropriate
• Docstrings for public APIs

---

Key Files to Review

Based on this feature, you should review:

• src/agentready/models/ - Understand Assessment, Finding, Attribute models
• src/agentready/services/scanner.py - Scanner orchestration
• src/agentready/assessors/base.py - BaseAssessor pattern
• src/agentready/reporters/ - Report generation
• CLAUDE.md - Project overview and guidelines
• BACKLOG.md - Full context of this feature

---

Testing Strategy

For this feature, ensure:

1. Unit tests for core logic (80%+ coverage)
2. Integration tests for end-to-end workflows
3. Edge case tests (empty inputs, missing files, errors)
4. Error handling tests (graceful degradation)

Run tests:

# All tests
pytest

# With coverage
pytest --cov=src/agentready --cov-report=html

# Specific test file
pytest tests/unit/test_feature.py -v

---

Success Criteria

This feature is complete when:

• ✅ All acceptance criteria from feature description are met
• ✅ Tests passing with >80% coverage for new code
• ✅ All linters passing (black, isort, ruff)
• ✅ Documentation updated
• ✅ PR created with clear description
• ✅ Self-tested end-to-end

---

Questions to Clarify (if needed)

If anything is unclear during implementation:

1. Check CLAUDE.md for project patterns
2. Review similar existing features
3. Ask for clarification in PR comments
4. Reference the original backlog item

---

Getting Started

# Clone and setup
git clone https://github.com/redhat/agentready.git
cd agentready

# Create virtual environment
uv venv && source .venv/bin/activate

# Install dependencies
uv pip install -e .
uv pip install pytest black isort ruff

# Create feature branch
git checkout -b 007-research-report-generator/updater-utility

# Start implementing!

---

Note: This is a coldstart prompt. You have all context needed to implement this feature independently. Read the linked files, follow the patterns, and deliver high-quality code with tests.

[jeremyeder]

@claude implement this.

[github-actions]

Claude finished @jeremyeder's task —— View job • claude/issue-7-20251122-0617 • Create PR ➔

---

Implementing Research Report Generator/Updater Utility ✅

Tasks

• Gather context: Read CLAUDE.md, existing CLI structure, schema files
• Review contracts/research-report-schema.md validation requirements
• Review agent-ready-codebase-attributes.md structure
• Understand existing ResearchLoader implementation
• Design module structure and CLI command hierarchy
• Implement research report parser (Markdown + YAML frontmatter)
• Implement research report formatter
• Implement agentready research validate command
• Implement agentready research init command
• Implement agentready research add-attribute command
• Implement agentready research bump-version command
• Implement agentready research format command
• Register research command group in main CLI
• Write unit tests (target >80% coverage)
• Write integration tests
• Update documentation (README.md, CLAUDE.md)
• Commit and push changes
• Create PR

---

Implementation Summary

Successfully implemented the Research Report Generator/Updater Utility (Issue #7) with comprehensive CLI commands, validation logic, and formatting utilities.

Files Created:

• src/agentready/cli/research.py - CLI command group with 5 subcommands (280 lines)
• src/agentready/services/research_formatter.py - Formatting utilities (320 lines)
• tests/unit/test_research_formatter.py - Unit tests with 80+ coverage (390 lines)
• tests/integration/test_research_cli.py - Integration tests (300 lines)

Files Modified:

• src/agentready/cli/main.py - Registered research command group
• README.md - Added CLI reference for research commands
• CLAUDE.md - Added Research Report Management section with examples

Commands Implemented:

1. agentready research validate FILE - Validates research report against schema

   • Checks metadata header (version, date)
   • Validates 25 attributes with required sections
   • Verifies tier assignments and references
   • Reports errors (blocking) vs warnings (non-critical)

2. agentready research init - Generates new research report from template

   • Creates proper YAML frontmatter
   • Includes all required sections
   • Pre-populates with 25 attribute placeholders
   • Includes tier structure and references section

3. agentready research add-attribute FILE - Adds new attribute

   • Inserts attribute with proper structure
   • Updates tier assignments automatically
   • Maintains category organization
   • Includes all required subsections

4. agentready research bump-version FILE - Updates version

   • Supports semantic versioning (major/minor/patch)
   • Accepts explicit version string
   • Updates both YAML frontmatter and body
   • Updates date to current timestamp

5. agentready research format FILE - Formats research report

   • Enforces consistent markdown style
   • Removes trailing whitespace
   • Limits consecutive blank lines
   • Supports check mode (--check)

Features:

• ✅ Schema validation per contracts/research-report-schema.md
• ✅ Semantic versioning with automatic date updates
• ✅ Attribute numbering consistency validation
• ✅ Markdown formatting (spacing, structure, whitespace)
• ✅ Template generation with all required sections
• ✅ Comprehensive test coverage (>80% for new code)
• ✅ Integration with existing ResearchLoader service
• ✅ Graceful error handling with actionable messages

Testing:

• 30+ unit tests covering all formatter methods
• 15+ integration tests for CLI commands
• Edge case coverage (duplicates, invalid formats, missing sections)
• Fixtures for sample reports and temporary files

Documentation:

• Updated README.md with CLI reference section
• Updated CLAUDE.md with detailed Research Report Management section
• Added usage examples and validation rules
• Documented error vs warning severity

---

Branch and PR

Branch: claude/issue-7-20251122-0617

---

| Branch: claude/issue-7-20251122-0617

[github-actions]

🎉 This issue has been resolved in version 1.11.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀