AgentSkillsCN

Revise Report Generation

通过汇总任务评论与经验教训，为史诗级功能生成结构化的修订报告。适用场景包括：(1) 当某个史诗级功能已完成或已取得重大进展时；(2) 当您希望整合来自多个任务的“修订学习”相关评论时；(3) 当您需要一份可追溯的报告，将任务与提交记录一一对应时。

SKILL.md
--- frontmatter
name: Revise Report Generation
description: >-
  Generates structured revise reports for Epics by aggregating task comments and learnings.
  Use when: (1) An Epic is completed or substantially progressed,
  (2) You want to consolidate "Revision Learning" comments from multiple tasks,
  (3) You need a traceability report linking tasks to commits.

Revise Report Generation

Generates structured revise reports to capture insights, learnings, and traceability from Beads Epics.

Prerequisites

  • •Beads Epic ID (e.g., bd-1234)
  • •Beads CLI (bd) installed and configured
  • •Tasks within the Epic populated with comments (specifically "Revision Learning" and "Commit")
  • •Confirm there are no open follow-up tasks created from PR review comments (final review should create these first, and revise report runs only after they are closed)

Report Structure

Epic Revise Report

1. Epic Summary

  • •Status of the Epic and child tasks.
  • •Overall completion rate.

2. Traceability Matrix

  • •Table mapping Task ID -> Title -> Status -> Commit Hash.

3. Evidence & Screenshots

  • •Screenshot directory location and count.
  • •Key screenshots with descriptions and links.
  • •Evidence organization by task.

4. Improvement Recommendations

  • •Documentation: Missing docs, outdated content, gaps in onboarding.
  • •Process: Workflow friction, automation opportunities, quality gate improvements.
  • •Rules & Standards: Cursor rules updates, coding standards violations, pattern inconsistencies.
  • •Tech Architecture: Code structure issues, dependency concerns, technical debt, performance considerations.

5. Action Items

  • •Prioritized, actionable steps to address improvements (Critical, High, Medium, Low).

Report Generation Process

Step 1: Data Gathering

Command: bd list --parent <EpicID> --json

  • •Retrieves all child tasks.
  • •Ensure any PR review follow-up tasks are closed before proceeding.

For each task: bd comments <TaskID> --json

  • •Retrieves all comments.
  • •Filter: Look for comments starting with:
    • •Revision Learning: (may include structured format with Category, Priority, Issue, Recommendation)
    • •Commit:
    • •Screenshots captured: (screenshot paths)
    • •Quality gates failed (to track rework)

Step 2: Analysis & Categorization

Traceability:

  • •Extract Commit Hash and Subject from Commit: comments.
  • •If missing, flag as "Missing Traceability".

Learning Categorization:

  • •Parse text after Revision Learning:.
  • •Structured Format Support: If learning includes structured fields:
    • •Extract Category: (Documentation|Process|Rules|Architecture)
    • •Extract Priority: (Critical|High|Medium|Low)
    • •Extract Issue: (description)
    • •Extract Recommendation: (actionable improvement)
    • •Extract Files/Rules Affected: (references)
  • •Auto-Classification: If not structured, classify into:
    • •Documentation: Missing context, unclear specs, outdated docs, onboarding gaps.
    • •Process: Instructions, prompting, workflow steps, automation opportunities, quality gates.
    • •Rules & Standards: Cursor rules, coding standards, pattern inconsistencies, best practices.
    • •Tech Architecture: Coding patterns, libraries, APIs, code structure, dependencies, technical debt, performance.

Screenshot Collection:

  • •Extract screenshot paths from Screenshots captured: comments.
  • •Group screenshots by task ID.
  • •Verify screenshot files exist in project directory.
  • •Count total screenshots and identify key screenshots for inclusion.

Step 3: Report Construction

Filename: YYYY-MM-DD_revise-report-epic-<EpicID>.md or YYYY-MM-DD_<epic-id>-improvements.md Location: .devagent/workspace/reviews/

Template:

markdown
# Epic Revise Report - <Epic Title>

**Date:** YYYY-MM-DD
**Epic ID:** <EpicID>
**Status:** <EpicStatus>

## Executive Summary
<2-3 sentence overview of the epic's execution and key takeaways>

## Traceability Matrix

| Task ID | Title | Status | Commit |
| :--- | :--- | :--- | :--- |
| bd-xxxx.1 | Implement Feature X | closed | `a1b2c3d` - feat: ... |
| bd-xxxx.2 | Fix Bug Y | in_progress | *Pending* |

## Evidence & Screenshots

- **Screenshot Directory**: `.devagent/workspace/reviews/<epic-id>/screenshots/`
- **Screenshots Captured**: [count] screenshots across [count] tasks
- **Key Screenshots**:
  - [Task ID]: [description] - `screenshots/[filename].png`
  - [Task ID]: [description] - `screenshots/[filename].png`

## Improvement Recommendations

### Documentation
- [ ] **[Priority] Missing**: [description] - [impact] - [files affected]
- [ ] **[Priority] Outdated**: [description] - [current state] - [needs update to]
- [ ] **[Priority] Gap**: [description] - [impact] - [recommendation]

### Process
- [ ] **[Priority] Workflow**: [friction point] - [suggestion] - [benefit]
- [ ] **[Priority] Automation**: [opportunity] - [implementation approach] - [benefit]
- [ ] **[Priority] Quality Gate**: [issue] - [recommendation] - [impact]

### Rules & Standards
- [ ] **[Priority] Cursor Rule**: [rule file] - [issue] - [recommended change]
- [ ] **[Priority] Pattern**: [pattern name] - [inconsistency] - [standard to apply]
- [ ] **[Priority] Coding Standard**: [violation] - [recommendation] - [files affected]

### Tech Architecture
- [ ] **[Priority] Structure**: [issue] - [current approach] - [recommended approach]
- [ ] **[Priority] Dependency**: [concern] - [risk] - [mitigation]
- [ ] **[Priority] Technical Debt**: [issue] - [impact] - [recommendation]
- [ ] **[Priority] Performance**: [concern] - [current state] - [optimization approach]

## Action Items
1. [ ] **[Priority]** <Action Item> - [from category]
2. [ ] **[Priority]** <Action Item> - [from category]

Validation

  • •Ensure every "Revision Learning" is captured.
  • •Ensure every "Commit" is linked.
  • •Verify Action Items are actionable.