repository-analysis-instructions.md

GitHub Repository Issues Analysis Instructions for Agents

This guide provides step-by-step instructions for agents to perform comprehensive GitHub repository analysis using structured frameworks and automated tooling.

🎯 Overview

Purpose: Generate comprehensive repository analysis reports focusing on issues, development patterns, and strategic insights.

Output: Professional analysis gist with evidence-based recommendations and strategic guidance.

Source Instructions: This instruction set: https://gist.github.com/paulyuk/e7898361ac9502e18c751ff771793fb9

🔧 Prerequisites

Required Capabilities:

• GitHub MCP server access (preferred) or GitHub API access
• Gist creation capabilities
• Structured analysis framework understanding
• Markdown documentation generation

Reference Framework: The Analysis Spec

📋 Step 1: Repository Input Collection

1.1 Repository URL Collection

Ask the user to provide:

Please provide the GitHub repository URL to analyze.
Format: https://github.com/owner/repository
Minimum required: owner/repository

Validation Requirements:

• Must contain at least owner/repo format
• Verify repository exists and is accessible
• Extract owner and repository name for API calls

1.2 Analysis Scope Selection

Ask the user to specify analysis timeframe:

What analysis scope would you prefer?
1. Last 180 days (default - focuses on recent activity)
2. All open issues (comprehensive current state)
3. Custom timeframe (specify date range)
4. Specific issue labels or milestones

Default Behavior: If not specified, use "Last 180 days" for focused recent analysis.

🔍 Step 2: Data Collection Strategy

2.1 Preferred Data Sources (Priority Order)

1. GitHub MCP Server (if available) - Use mcp_github_* tools
2. GitHub API directly - Fallback option
3. Manual collection - Last resort

2.2 GitHub MCP Server Data Collection

Primary Tools to Use:

mcp_github_list_issues - For issue collection with filters
mcp_github_get_issue - For detailed issue analysis
mcp_github_get_issue_comments - For comment analysis
mcp_github_list_releases - For release history context

Collection Parameters Based on User Choice:

• Last 180 days: since parameter with calculated date
• All open issues: state=OPEN without date filters
• Custom timeframe: User-specified date ranges

2.3 Data Collection Focus Areas

Prioritize Issues With:

• Reproducible bugs with clear reproduction steps
• Feature enhancement requests with community support
• Compatibility and dependency conflicts
• Performance and reliability concerns
• Documentation gaps and user experience issues
• Security vulnerabilities and fixes

📊 Step 3: Analysis Framework Application

3.1 Content Overview Structure

## Content Overview

**Recent Activity Analysis:**
- X Open Issues: [timeframe-specific summary]
- Y Closed Issues: [historical context if relevant]
- Z Releases: [recent release activity]
- Key Development Priorities: [identified themes]

**Development Focus Areas:**
- [Theme 1]: [brief description]
- [Theme 2]: [brief description]
- [Theme 3]: [brief description]

3.2 Evidence Assessment Framework

For Each Major Finding:

### [Finding Title] - Evidence Strength: **[HIGH/MEDIUM/LOW]**
**Supporting Evidence:**
- **Issue #XXX**: [specific description with impact]
- **Pattern Analysis**: [recurring themes]
- **Context**: [additional supporting information]

**Strategic Impact:** **[CRITICAL/HIGH/MEDIUM/LOW]** - [explanation]

3.3 Strategic Insights Structure

## Strategic Insights & Gaps

### **Critical Gaps Identified:**
1. **[Gap Category]**: [detailed description]
2. **[Gap Category]**: [detailed description]

### **[Assessment Category] Assessment:**
**Strengths:**
- [Strength 1 with evidence]
- [Strength 2 with evidence]

**Critical Weaknesses:**
- [Weakness 1 with impact]
- [Weakness 2 with impact]

📝 Step 4: Documentation Requirements

4.1 Analysis Report Structure

# [Repository Name] - Comprehensive Repository Analysis

## Executive Summary
[2-3 paragraph overview with key findings]

## Content Overview
[Activity metrics and development priorities]

## Key Claims & Evidence Assessment
[3-5 major findings with evidence strength]

## Strategic Insights & Gaps
[Gap analysis and architectural assessment]

## Recommendations
[Targeted recommendations for different stakeholders]

---
**Analysis Methodology**: [Brief methodology description]
**Source Instructions**: https://gist.github.com/paulyuk/e7898361ac9502e18c751ff771793fb9

4.2 Gist Creation Requirements

Always Create TWO Gists:

1. Analysis Report Gist (Main Output):

   • Filename: [repository-name]-analysis-[date].md
   • Description: "Comprehensive analysis of [owner/repo] repository"
   • Content: Full analysis report

2. Specific Instructions Gist (Process Documentation):

   • Filename: analysis-instructions-used-[date].md
   • Description: "Specific instructions used for [owner/repo] analysis"
   • Content: Customized instructions based on user inputs

🎯 Step 5: Stakeholder-Specific Recommendations

5.1 Standard Recommendation Categories

## Recommendations

### **For [Project] Team:**
1. **[PRIORITY]**: [specific actionable recommendation]
2. **[PRIORITY]**: [specific actionable recommendation]

### **For Enterprise Adopters:**
1. **[URGENCY]**: [implementation guidance]
2. **[CONSIDERATION]**: [evaluation criteria]

### **For Contributors:**
1. **[IMPACT LEVEL]**: [contribution opportunities]
2. **[IMPACT LEVEL]**: [community engagement areas]

5.2 Priority Levels

• URGENT/CRITICAL: Immediate action required
• HIGH: Near-term priority (1-3 months)
• MEDIUM: Medium-term planning (3-6 months)
• LONG-TERM: Strategic planning (6+ months)

🔄 Step 6: Quality Assurance Checklist

Before Finalizing Analysis:

• All major issues have evidence strength assessments
• Thematic categorization is complete and coherent
• Strategic recommendations include specific, actionable items
• Examples support claims with concrete evidence
• Analysis addresses repository-specific context
• Both required gists are created
• Source instructions link is included
• Repository-specific documentation links are provided

🚀 Step 7: Output Delivery Protocol

7.1 Primary Deliverable

Analysis Report Gist containing:

• Executive summary with key findings
• Evidence-based analysis with strength assessments
• Strategic recommendations for multiple stakeholders
• Link back to source instructions
• Repository-specific documentation references

7.2 Process Documentation

Instructions Gist containing:

• User inputs collected (repository, scope, preferences)
• Specific tools and methods used
• Data collection parameters applied
• Analysis framework customizations
• Link back to master instructions

7.3 User Communication

Final Response Format:

I've completed the comprehensive analysis of [owner/repo]. Here are your deliverables:

📊 **Analysis Report**: [gist-url-1]
📋 **Process Documentation**: [gist-url-2]

Key findings include [brief 1-2 sentence summary of critical insights].

The analysis covers [scope description] and provides strategic recommendations for [stakeholder types].

📚 Reference Materials

• Analysis Framework: https://gist.github.com/paulyuk/95aed4c8418ed8d7fe481338e032b315
• Example Analysis: https://gist.github.com/paulyuk/3915a6786456c4169f3b8a65eb6b1a2d
• Source Instructions: https://gist.github.com/paulyuk/e7898361ac9502e18c751ff771793fb9

🔄 Iteration and Improvement

For Continuous Improvement:

• Track analysis quality and user feedback
• Update framework based on repository-specific learnings
• Enhance automation capabilities with new MCP tools
• Maintain consistency across different repository types
• Share insights with instruction set maintainers

---

Instructions Version: 2.0 (Enhanced for Agent Use) Last Updated: August 27, 2025 Maintained by: Repository Analysis Framework Team