diff --git a/README.md b/README.md index e319401..9312bac 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ A sample family of reusable [GitHub Agentic Workflows](https://github.github.com ### Research, Status & Planning Workflows - [📚 Weekly Research](docs/weekly-research.md) - Collect research updates and industry trends +- [📊 Weekly Issue Summary](docs/weekly-issue-summary.md) - Weekly issue activity report with trend charts and recommendations - [👥 Daily Repo Status](docs/daily-repo-status.md) - Assess repository activity and create status reports - [👥 Daily Team Status](docs/daily-team-status.md) - Create upbeat daily team activity summaries with productivity insights - [📋 Daily Plan](docs/daily-plan.md) - Update planning issues for team coordination diff --git a/docs/link-checker.md b/docs/link-checker.md index 2b39b7a..f819818 100644 --- a/docs/link-checker.md +++ b/docs/link-checker.md @@ -2,7 +2,7 @@ **Workflow file:** [`.github/workflows/link-checker.md`](../.github/workflows/link-checker.md) -## What it does +## What It Does The Link Checker is an automated agentic workflow that: @@ -12,7 +12,7 @@ The Link Checker is an automated agentic workflow that: 4. **Remembers unfixable links** using cache memory to avoid repeated attempts 5. **Creates pull requests** with the fixed links when changes are made -## How it works +## How It Works ````mermaid graph LR @@ -66,7 +66,7 @@ The workflow maintains a persistent cache of unfixable broken links: This prevents the workflow from repeatedly attempting to fix links that are permanently broken. -## When it runs +## When It Runs - **Daily on weekdays** (automatic fuzzy scheduling) - **Manually** via workflow_dispatch (automatically enabled for fuzzy schedules) diff --git a/docs/weekly-issue-summary.md b/docs/weekly-issue-summary.md new file mode 100644 index 0000000..9f3549c --- /dev/null +++ b/docs/weekly-issue-summary.md @@ -0,0 +1,73 @@ +# 📊 Weekly Issue Summary + +> For an overview of all available workflows, see the [main README](../README.md). + +The [Weekly Issue Summary workflow](../workflows/weekly-issue-summary.md?plain=1) generates a comprehensive weekly report on issue activity, including trend charts, resolution time analysis, and actionable recommendations. It runs automatically every Monday, giving maintainers a clear snapshot of repository health over the past week and the past 30 days. + +## Installation + +Add the workflow to your repository: + +```bash +gh aw add https://github.com/githubnext/agentics/blob/main/workflows/weekly-issue-summary.md +``` + +Then compile: + +```bash +gh aw compile +``` + +## How It Works + +````mermaid +graph LR + A[Monday Schedule] --> B[Collect Issue Data] + B --> C[Generate Trend Charts] + C --> D[Upload Charts] + D --> E[Create Weekly Discussion] +```` + +Each Monday at 3 PM UTC, the workflow: + +1. **Collects issue data** — Queries issues opened and closed over the past 30 days, computing daily counts and resolution times +2. **Generates trend charts** — Uses Python (pandas + matplotlib + seaborn) to produce two high-quality charts: + - **Issue Activity Trends** — Weekly opened vs. closed counts and running open total + - **Resolution Time Trends** — Average and median days-to-close over time +3. **Uploads charts** — Stores charts as GitHub assets and collects their URLs +4. **Creates a discussion** — Posts a `[Weekly Summary]` discussion in the **Audits** category with embedded charts, statistics, and recommendations + +Older `[Weekly Summary]` discussions are automatically closed when a new one is created, keeping the discussions list clean. + +## What You Get + +Each weekly discussion includes: + +- **Overview paragraph** comparing this week to last week +- **Two embedded trend charts** showing activity and resolution patterns +- **Key trends** highlighting common issue types, label distributions, and notable patterns +- **Summary statistics table** with week-over-week comparisons +- **Full issue list** in a collapsible section +- **Recommendations** for the upcoming week + +## Configuration + +The workflow runs every Monday at 3 PM UTC. To change the schedule, edit the `cron` expression in the workflow frontmatter: + +```yaml +on: + schedule: + - cron: "0 15 * * 1" # Monday 3 PM UTC +``` + +## Requirements + +The workflow requires: + +- A **GitHub Discussions** category named `audits` (create it in your repository's Discussions settings) +- Python 3 available on the Actions runner (standard on GitHub-hosted runners) +- Network access to install Python packages (`pandas`, `matplotlib`, `seaborn`) + +## Permissions + +The workflow uses `issues: read` permission only — it reads issue data but never modifies issues. diff --git a/workflows/weekly-issue-summary.md b/workflows/weekly-issue-summary.md new file mode 100644 index 0000000..fb4a1fd --- /dev/null +++ b/workflows/weekly-issue-summary.md @@ -0,0 +1,151 @@ +--- +description: Creates weekly summary of issue activity including trends, charts, and insights every Monday +timeout-minutes: 20 +strict: true +on: + schedule: + - cron: "0 15 * * 1" # Weekly on Mondays at 3 PM UTC + workflow_dispatch: +permissions: + issues: read +engine: copilot +network: + allowed: + - defaults + - python +tools: + edit: + bash: + - "*" + github: + lockdown: true + toolsets: + - issues +safe-outputs: + upload-asset: + create-discussion: + title-prefix: "[Weekly Summary] " + category: "audits" + close-older-discussions: true +steps: + - name: Setup Python environment + run: | + mkdir -p /tmp/charts /tmp/data + pip install --user --quiet numpy pandas matplotlib seaborn scipy + python3 -c "import pandas, matplotlib, seaborn; print('Python environment ready')" +--- + +# Weekly Issue Summary + +Create a comprehensive weekly summary of issue activity for repository ${{ github.repository }}. + +## Step 1: Collect Issue Data + +Use GitHub API tools to gather data for the past 30 days: + +1. **Issue Activity Data** — Count of issues opened per day, closed per day, and running open count +2. **Issue Resolution Data** — Average time to close issues, distribution of issue lifespans, breakdown by label + +Fetch enough issues to compute weekly and daily trends over the past 30 days. Use the GitHub toolset to query issues filtered by `created` and `closed` dates. + +## Step 2: Generate Trend Charts + +Write Python scripts to create exactly 2 high-quality trend charts and execute them via bash. + +### Chart 1: Issue Activity Trends + +Save data to `/tmp/data/issue_activity.csv` with columns: `date,opened,closed,open_total` + +Generate a multi-line chart: +- Issues opened per week (bar or line) +- Issues closed per week (bar or line) +- Running total of open issues (secondary line) +- X-axis: last 12 weeks, Y-axis: count +- Save as `/tmp/charts/issue_activity_trends.png` at 300 DPI, 12×7 inches +- Use seaborn whitegrid style with a professional color palette + +### Chart 2: Issue Resolution Time Trends + +Save data to `/tmp/data/issue_resolution.csv` with columns: `date,avg_days,median_days` + +Generate a line chart with moving average overlay: +- Average time to close (7-day moving average line) +- Median time to close +- Shaded variance band +- X-axis: last 30 days, Y-axis: days to resolution +- Save as `/tmp/charts/issue_resolution_trends.png` at 300 DPI, 12×7 inches + +Run your Python scripts via bash and verify the charts exist before proceeding. + +### Python Notes + +- Use pandas for data manipulation and datetime handling +- Use `matplotlib.pyplot` and `seaborn` for visualization +- Apply `plt.tight_layout()` before saving +- Handle sparse data gracefully (use bar charts if fewer than 7 data points) +- Set `matplotlib.use('Agg')` to avoid display errors in headless environments + +## Step 3: Upload Charts + +Upload both chart images using the `upload-asset` safe output tool. Collect the returned URLs to embed in the discussion. + +## Step 4: Create Weekly Discussion + +Create a discussion with the title format: `Weekly Summary - [YYYY-MM-DD]` + +### Formatting Guidelines + +- Use `###` for main sections, `####` for subsections (discussion title is the h1) +- Wrap long lists in `
` collapsible sections +- Keep critical information (overview, trends, statistics, recommendations) always visible +- Keep optional detail (full issue lists, verbose breakdowns) in collapsible sections + +### Discussion Structure + +```markdown +### 📊 Weekly Overview + +[1–2 paragraphs: total issues opened and closed this week, how that compares to the previous week, key theme or pattern in the issues] + +### 📈 Issue Activity Trends + +#### Weekly Activity Patterns +![Issue Activity Trends]({chart_1_url}) + +[2–3 sentences: describe the trend — are issues accumulating, being resolved quickly, or holding steady?] + +#### Resolution Time Analysis +![Issue Resolution Trends]({chart_2_url}) + +[2–3 sentences: how quickly are issues being resolved? improving or slowing down?] + +### 🔑 Key Trends + +[Bullet list of 3–5 notable patterns: common issue types, label distribution, new contributors filing issues, recurring topics, etc.] + +### 📋 Summary Statistics + +| Metric | This Week | Last Week | Trend | +|--------|-----------|-----------|-------| +| Issues Opened | X | X | ↑/↓/→ | +| Issues Closed | X | X | ↑/↓/→ | +| Currently Open | X | X | ↑/↓/→ | +| Avg Close Time | X days | X days | ↑/↓/→ | + +
+Full Issue List (This Week) + +[Numbered list of all issues opened this week with title, number, author, labels] + +
+ +### 💡 Recommendations for Upcoming Week + +[3–5 actionable suggestions: which issues to prioritize, patterns that suggest backlog growth, labels that need attention, etc.] +``` + +## Step 5: Notes + +- If fewer than 7 days of data are available, generate charts with available data and note the limited range +- If no issues exist this week, still create a discussion noting the quiet week +- Always create the discussion even if charts fail to generate (omit chart sections and explain)