|
| 1 | +# 📊 Repository Quality Improver |
| 2 | + |
| 3 | +> For an overview of all available workflows, see the [main README](../README.md). |
| 4 | +
|
| 5 | +The [Repository Quality Improver workflow](../workflows/repository-quality-improver.md?plain=1) analyzes your repository from a different quality angle every weekday, producing an issue with findings and actionable improvement tasks. |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | +Add the workflow to your repository: |
| 10 | + |
| 11 | +```bash |
| 12 | +gh aw add https://github.com/githubnext/agentics/blob/main/workflows/repository-quality-improver.md |
| 13 | +``` |
| 14 | + |
| 15 | +Then compile: |
| 16 | + |
| 17 | +```bash |
| 18 | +gh aw compile |
| 19 | +``` |
| 20 | + |
| 21 | +> **Note**: This workflow creates GitHub Issues with the `quality` and `automated-analysis` labels. |
| 22 | +
|
| 23 | +## What It Does |
| 24 | + |
| 25 | +The Repository Quality Improver runs on weekdays and: |
| 26 | + |
| 27 | +1. **Selects a Focus Area** — Picks a different quality dimension each run, using a rotating strategy to ensure broad, diverse coverage over time |
| 28 | +2. **Analyzes the Repository** — Examines source code, configuration, tests, and documentation from the chosen angle |
| 29 | +3. **Creates an Issue** — Posts a structured report with findings, metrics, and 3–5 actionable improvement tasks |
| 30 | +4. **Tracks History** — Remembers previous focus areas (using cache memory) to avoid repetition and maximize coverage |
| 31 | + |
| 32 | +## How It Works |
| 33 | + |
| 34 | +````mermaid |
| 35 | +graph LR |
| 36 | + A[Load Focus History] --> B[Select Focus Area] |
| 37 | + B --> C{Strategy?} |
| 38 | + C -->|60%| D[Custom: Repo-specific area] |
| 39 | + C -->|30%| E[Standard: Code/Docs/Tests/Security...] |
| 40 | + C -->|10%| F[Reuse: Most impactful recent area] |
| 41 | + D --> G[Analyze Repository] |
| 42 | + E --> G |
| 43 | + F --> G |
| 44 | + G --> H[Create Issue Report] |
| 45 | + H --> I[Update Cache Memory] |
| 46 | +```` |
| 47 | + |
| 48 | +### Focus Area Strategy |
| 49 | + |
| 50 | +The workflow follows a deliberate diversity strategy across runs: |
| 51 | + |
| 52 | +- **60% Custom areas** — Repository-specific issues the agent discovers by inspecting the codebase: e.g., "Error Message Clarity", "Contributor Onboarding Experience", "API Consistency" |
| 53 | +- **30% Standard categories** — Established quality dimensions: Code Quality, Documentation, Testing, Security, Performance, CI/CD, Dependencies, Code Organization, Accessibility, Usability |
| 54 | +- **10% Revisits** — Revisit the most impactful area from recent history for follow-up |
| 55 | + |
| 56 | +Over ten runs, the agent will typically explore 6–7+ unique quality dimensions. |
| 57 | + |
| 58 | +### Output: GitHub Issues |
| 59 | + |
| 60 | +Each run produces one issue containing: |
| 61 | + |
| 62 | +- **Executive Summary** — 2–3 paragraphs of key findings |
| 63 | +- **Full Analysis** — Detailed metrics, strengths, and areas for improvement (collapsed) |
| 64 | +- **Improvement Tasks** — 3–5 concrete, prioritized tasks with file-level specificity |
| 65 | +- **Historical Context** — Table of previous focus areas for reference |
| 66 | + |
| 67 | +You can comment on the issue to request follow-up actions or add it to a project board for tracking. |
| 68 | + |
| 69 | +## Example Reports |
| 70 | + |
| 71 | +From the original gh-aw use (62% merge rate via causal chain): |
| 72 | +- [CI/CD Optimization report](https://github.com/github/gh-aw/discussions/6863) — identified pipeline inefficiencies leading to multiple PRs |
| 73 | +- [Performance report](https://github.com/github/gh-aw/discussions/13280) — surfaced bottlenecks addressed by downstream agents |
| 74 | + |
| 75 | +## Configuration |
| 76 | + |
| 77 | +The workflow uses these default settings: |
| 78 | + |
| 79 | +| Setting | Default | Description | |
| 80 | +|---------|---------|-------------| |
| 81 | +| Schedule | Daily on weekdays | When to run the analysis | |
| 82 | +| Issue labels | `quality`, `automated-analysis` | Labels applied to created issues | |
| 83 | +| Max issues per run | 1 | Prevents duplicate reports | |
| 84 | +| Issue expiry | 2 days | Older issues are closed when a new one is posted | |
| 85 | +| Timeout | 20 minutes | Per-run time limit | |
| 86 | + |
| 87 | +## Customization |
| 88 | + |
| 89 | +```bash |
| 90 | +gh aw edit repository-quality-improver |
| 91 | +``` |
| 92 | + |
| 93 | +Common customizations: |
| 94 | +- **Change issue labels** — Set the `labels` field in `safe-outputs.create-issue` to labels that exist in your repository |
| 95 | +- **Adjust the schedule** — Change the cron to run less frequently if your codebase changes slowly |
| 96 | +- **Add custom standard areas** — Extend the standard categories list with areas relevant to your project |
| 97 | + |
| 98 | +## Tips for Success |
| 99 | + |
| 100 | +1. **Review open issues** — Check the labeled issues regularly to pick up quick wins |
| 101 | +2. **Add issues to a project board** — Track improvement tasks using GitHub Projects for visibility |
| 102 | +3. **Let the diversity algorithm work** — Avoid overriding the focus area too frequently; the rotating strategy ensures broad coverage over time |
| 103 | +4. **Review weekly** — Check recent issues to pick up any quick wins |
| 104 | + |
| 105 | +## Source |
| 106 | + |
| 107 | +This workflow is adapted from [Peli's Agent Factory](https://github.github.io/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-improvement/), where it achieved a 62% merge rate (25 merged PRs out of 40 proposed) via a causal discussion → issue → PR chain. |
| 108 | + |
| 109 | +## Related Workflows |
| 110 | + |
| 111 | +- [Daily File Diet](daily-file-diet.md) — Targeted refactoring for oversized files |
| 112 | +- [Code Simplifier](code-simplifier.md) — Simplify recently modified code |
| 113 | +- [Duplicate Code Detector](duplicate-code-detector.md) — Find and remove code duplication |
0 commit comments