aidevops 2.52.1

package/.agent/workflows/error-feedback.md

@@ -0,0 +1,578 @@
+---
+description: Error checking, debugging, and feedback loops for CI/CD
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: true
+  task: true
+---
+
+# Error Checking and Feedback Loops
+
+This document outlines processes for error checking, debugging, and establishing feedback loops for autonomous CI/CD operation.
+
+The goal is to enable AI assistants to identify, diagnose, and fix issues with minimal human intervention.
+
+## Table of Contents
+
+- [GitHub Actions Workflow Monitoring](#github-actions-workflow-monitoring)
+- [Local Build and Test Feedback](#local-build-and-test-feedback)
+- [Code Quality Tool Integration](#code-quality-tool-integration)
+- [Automated Error Resolution](#automated-error-resolution)
+- [Feedback Loop Architecture](#feedback-loop-architecture)
+- [When to Consult Humans](#when-to-consult-humans)
+
+## GitHub Actions Workflow Monitoring
+
+### Checking Workflow Status via GitHub CLI
+
+```bash
+# Get recent workflow runs
+gh run list --limit 10
+
+# Get failed runs only
+gh run list --status failure --limit 5
+
+# Get details for a specific run
+gh run view {run_id}
+
+# Get logs for a failed run
+gh run view {run_id} --log-failed
+
+# Watch a running workflow
+gh run watch {run_id}
+```
+
+### Checking via GitHub API
+
+```bash
+# Get recent workflow runs
+gh api repos/{owner}/{repo}/actions/runs --jq '.workflow_runs[:5] | .[] | "\(.name): \(.conclusion // .status)"'
+
+# Get failed runs
+gh api repos/{owner}/{repo}/actions/runs?status=failure
+
+# Get jobs for a specific run
+gh api repos/{owner}/{repo}/actions/runs/{run_id}/jobs
+```
+
+### Common GitHub Actions Errors and Solutions
+
+| Error | Solution |
+|-------|----------|
+| Missing action version | Update to latest: `uses: actions/checkout@v4` |
+| Deprecated action | Replace with recommended alternative |
+| Secret not found | Verify secret name in repository settings |
+| Permission denied | Check workflow permissions or GITHUB_TOKEN scope |
+| Timeout | Increase timeout or optimize slow steps |
+| Cache miss | Verify cache keys and paths |
+
+#### Example Fixes
+
+**Outdated Action:**
+
+```yaml
+# Before
+uses: actions/upload-artifact@v3
+
+# After
+uses: actions/upload-artifact@v4
+```
+
+**Concurrency Control:**
+
+```yaml
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+```
+
+## Local Build and Test Feedback
+
+### Running Local Tests
+
+```bash
+# JavaScript/Node.js
+npm test
+npm run test:coverage
+
+# Python
+pytest
+pytest --cov=module/
+
+# PHP
+composer test
+vendor/bin/phpunit
+
+# Go
+go test ./...
+
+# Rust
+cargo test
+```
+
+### Capturing Test Output
+
+```bash
+# Capture output for analysis
+npm test > test-output.log 2>&1
+
+# Parse for errors
+grep -i 'error\|fail\|exception' test-output.log
+
+# Get structured results (if available)
+cat test-results.json | jq '.failures'
+```
+
+### Common Local Test Errors
+
+| Error Type | Diagnosis | Solution |
+|------------|-----------|----------|
+| Dependency missing | Check error for package name | `npm install` / `pip install` |
+| Port in use | Check error for port number | Kill process or use different port |
+| Timeout | Test takes too long | Increase timeout or optimize |
+| Database connection | DB not running | Start database service |
+| Permission denied | File/directory access | Check permissions, run with proper user |
+
+## Code Quality Tool Integration
+
+### Running Quality Checks
+
+```bash
+# Universal quality check (aidevops)
+bash ~/Git/aidevops/.agent/scripts/linters-local.sh
+
+# ShellCheck (bash scripts)
+shellcheck script.sh
+
+# ESLint (JavaScript)
+npx eslint . --format json
+
+# Pylint (Python)
+pylint module/ --output-format=json
+
+# PHP CodeSniffer
+composer phpcs
+```
+
+### Auto-Fixing Issues
+
+```bash
+# Codacy auto-fix
+bash ~/Git/aidevops/.agent/scripts/codacy-cli.sh analyze --fix
+
+# Qlty auto-format
+bash ~/Git/aidevops/.agent/scripts/qlty-cli.sh fmt --all
+
+# ESLint auto-fix
+npx eslint . --fix
+
+# PHP Code Beautifier
+composer phpcbf
+```
+
+### Monitoring PR Feedback
+
+```bash
+# Get PR comments
+gh pr view {pr_number} --comments
+
+# Get PR reviews
+gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews
+
+# Get check runs for PR
+gh pr checks {pr_number}
+```
+
+### Efficient Quality Tool Feedback via GitHub API
+
+**Why use the API directly?** The GitHub Checks API provides structured access to all code quality tool feedback (Codacy, CodeFactor, SonarCloud, CodeRabbit, etc.) without needing to visit each tool's dashboard. This enables rapid iteration.
+
+#### Get All Check Runs for a PR/Commit
+
+```bash
+# Get check runs for latest commit on current branch
+gh api repos/{owner}/{repo}/commits/$(git rev-parse HEAD)/check-runs \
+  --jq '.check_runs[] | {name: .name, status: .status, conclusion: .conclusion}'
+
+# Get check runs for a specific PR
+gh api repos/{owner}/{repo}/commits/$(gh pr view {pr_number} --json headRefOid -q .headRefOid)/check-runs \
+  --jq '.check_runs[] | {name: .name, conclusion: .conclusion, url: .html_url}'
+
+# Filter for failed checks only
+gh api repos/{owner}/{repo}/commits/$(git rev-parse HEAD)/check-runs \
+  --jq '.check_runs[] | select(.conclusion == "failure" or .conclusion == "action_required") | {name: .name, conclusion: .conclusion}'
+```
+
+#### Get Detailed Annotations (Line-Level Issues)
+
+```bash
+# Get annotations from a specific check run (e.g., Codacy)
+gh api repos/{owner}/{repo}/check-runs/{check_run_id}/annotations \
+  --jq '.[] | {path: .path, line: .start_line, level: .annotation_level, message: .message}'
+
+# Get all annotations from all check runs for a commit
+for id in $(gh api repos/{owner}/{repo}/commits/$(git rev-parse HEAD)/check-runs --jq '.check_runs[].id'); do
+  echo "=== Check Run $id ==="
+  gh api repos/{owner}/{repo}/check-runs/$id/annotations --jq '.[] | "\(.path):\(.start_line) [\(.annotation_level)] \(.message)"' 2>/dev/null
+done
+```
+
+#### Quick Status Check Script
+
+```bash
+#!/bin/bash
+# Quick quality check status for current branch
+
+REPO="${GITHUB_REPOSITORY:-$(gh repo view --json nameWithOwner -q .nameWithOwner)}"
+COMMIT=$(git rev-parse HEAD)
+
+echo "=== Quality Check Status for $COMMIT ==="
+gh api "repos/$REPO/commits/$COMMIT/check-runs" \
+  --jq '.check_runs[] | "\(.conclusion // .status | ascii_upcase)\t\(.name)"' | sort
+
+echo ""
+echo "=== Failed Checks Details ==="
+gh api "repos/$REPO/commits/$COMMIT/check-runs" \
+  --jq '.check_runs[] | select(.conclusion == "failure") | "❌ \(.name): \(.output.summary // "See details")"'
+```
+
+#### Tool-Specific API Access
+
+**Codacy:**
+
+```bash
+# Get Codacy check run details
+gh api repos/{owner}/{repo}/commits/{sha}/check-runs \
+  --jq '.check_runs[] | select(.app.slug == "codacy-production") | {conclusion: .conclusion, summary: .output.summary}'
+```
+
+**CodeRabbit:**
+
+```bash
+# Get CodeRabbit review comments
+gh api repos/{owner}/{repo}/pulls/{pr_number}/comments \
+  --jq '.[] | select(.user.login | contains("coderabbit")) | {path: .path, line: .line, body: .body}'
+```
+
+**SonarCloud:**
+
+```bash
+# Get SonarCloud check run
+gh api repos/{owner}/{repo}/commits/{sha}/check-runs \
+  --jq '.check_runs[] | select(.name | contains("SonarCloud")) | {conclusion: .conclusion, url: .details_url}'
+```
+
+#### Automated Feedback Loop Pattern
+
+```bash
+#!/bin/bash
+# Automated quality feedback loop
+
+check_and_report() {
+    local repo="$1"
+    local sha="$2"
+    
+    echo "Checking quality status..."
+    
+    # Get all check conclusions
+    local checks
+    checks=$(gh api "repos/$repo/commits/$sha/check-runs" \
+      --jq '.check_runs[] | {name: .name, conclusion: .conclusion, id: .id}')
+    
+    # Report failures with details
+    echo "$checks" | jq -r 'select(.conclusion == "failure") | .id' | while read -r id; do
+        echo "=== Failure in check $id ==="
+        gh api "repos/$repo/check-runs/$id/annotations" \
+          --jq '.[] | "  \(.path):\(.start_line) - \(.message)"'
+    done
+    
+    # Summary
+    local passed failed
+    passed=$(echo "$checks" | jq -r 'select(.conclusion == "success") | .name' | wc -l)
+    failed=$(echo "$checks" | jq -r 'select(.conclusion == "failure") | .name' | wc -l)
+    
+    echo ""
+    echo "Summary: $passed passed, $failed failed"
+}
+
+# Usage
+check_and_report "owner/repo" "$(git rev-parse HEAD)"
+```
+
+### Processing Code Quality Feedback
+
+1. **Collect all feedback:**
+
+   ```bash
+   gh pr view {number} --comments --json comments
+   gh api repos/{owner}/{repo}/pulls/{number}/reviews
+   ```
+
+2. **Categorize issues:**
+   - Critical: Security, breaking bugs
+   - High: Quality violations, potential bugs
+   - Medium: Style issues, best practices
+   - Low: Documentation, minor improvements
+
+3. **Prioritize fixes:**
+   - Address critical issues first
+   - Group related issues for efficient fixing
+   - Consider dependencies between issues
+
+## Automated Error Resolution
+
+### Error Resolution Workflow
+
+```text
+1. Identify Error
+   ↓
+2. Categorize Error (type, severity)
+   ↓
+3. Search for Known Solution
+   ↓
+4. Apply Fix
+   ↓
+5. Verify Fix (run tests)
+   ↓
+6. Document Solution
+```
+
+### Processing Workflow Failures
+
+```bash
+# 1. Get failed workflow
+gh run list --status failure --limit 1
+
+# 2. Get failure details
+gh run view {run_id} --log-failed
+
+# 3. Identify the failing step and error
+
+# 4. Apply fix based on error type
+
+# 5. Push fix and monitor
+git add . && git commit -m "Fix: CI error description"
+git push origin {branch}
+gh run watch
+```
+
+### Common Fix Patterns
+
+**Dependency Issues:**
+
+```bash
+# Update lockfile
+npm ci  # or: npm install
+composer install
+
+# Clear caches
+npm cache clean --force
+composer clear-cache
+```
+
+**Test Failures:**
+
+```bash
+# Run specific failing test
+npm test -- --grep "failing test name"
+
+# Run with verbose output
+npm test -- --verbose
+
+# Update snapshots if intentional changes
+npm test -- --updateSnapshot
+```
+
+**Linting Errors:**
+
+```bash
+# Auto-fix what's possible
+npm run lint:fix
+
+# Review remaining issues
+npm run lint -- --format stylish
+```
+
+## Feedback Loop Architecture
+
+### Complete Feedback Loop System
+
+```text
+Code Changes ──► Local Testing ──► GitHub Actions
+     │                │                  │
+     ▼                ▼                  ▼
+AI Assistant ◄── Error Analysis ◄── Status Check
+     │
+     ▼
+Fix Generation ──► Verification ──► Human Review (if needed)
+```
+
+### Key Components
+
+| Component | Purpose | Tools |
+|-----------|---------|-------|
+| Code Changes | Initial modifications | Git |
+| Local Testing | Immediate feedback | npm test, pytest |
+| GitHub Actions | Remote validation | gh CLI |
+| Status Check | Monitor workflows | gh run list |
+| Error Analysis | Parse and categorize | grep, jq |
+| AI Assistant | Central intelligence | This guide |
+| Fix Generation | Create solutions | Edit, Write tools |
+| Verification | Confirm fix works | Tests, CI |
+| Human Review | Complex decisions | When needed |
+
+### Implementing the Loop
+
+```bash
+#!/bin/bash
+# Continuous monitoring script pattern
+
+check_and_fix() {
+    # Check for failures - declare and assign separately per SC2155
+    local failures
+    failures=$(gh run list --status failure --limit 1 --json conclusion -q '.[].conclusion')
+    
+    if [[ "$failures" == "failure" ]]; then
+        # Get failure details - declare and assign separately per SC2155
+        local run_id
+        local logs
+        run_id=$(gh run list --status failure --limit 1 --json databaseId -q '.[].databaseId')
+        logs=$(gh run view "$run_id" --log-failed)
+        
+        # Analyze and report
+        echo "Failure detected in run $run_id"
+        echo "$logs" | grep -i 'error\|fail' | head -20
+        
+        # Suggest fixes based on error patterns
+        analyze_error "$logs"
+    fi
+}
+
+analyze_error() {
+    local logs="$1"
+    
+    if echo "$logs" | grep -q "npm ERR!"; then
+        echo "Suggestion: Run 'npm ci' to reinstall dependencies"
+    elif echo "$logs" | grep -q "EACCES"; then
+        echo "Suggestion: Check file permissions"
+    elif echo "$logs" | grep -q "timeout"; then
+        echo "Suggestion: Increase timeout or optimize slow operations"
+    fi
+}
+```
+
+## When to Consult Humans
+
+### Scenarios Requiring Human Input
+
+| Scenario | Reason | What to Provide |
+|----------|--------|-----------------|
+| Product design decisions | Requires business context | Options with trade-offs |
+| Security-critical changes | Risk assessment needed | Security implications |
+| Architectural decisions | Long-term impact | Architecture options |
+| Deployment approvals | Production risk | Deployment plan |
+| Novel problems | No precedent | Research findings |
+| External service issues | Out of control | Status and workarounds |
+| Ambiguous requirements | Clarification needed | Questions and assumptions |
+
+### Effective Human Consultation
+
+When consulting humans, provide:
+
+**Issue Summary:** Brief description of the problem.
+
+**Context:**
+
+- What were you trying to accomplish?
+- What happened instead?
+
+**Error Details:** Include specific error messages or logs.
+
+**Attempted Solutions:**
+
+1. Tried X - Result: Y
+2. Tried Z - Result: W
+
+**Questions:**
+
+1. Specific question requiring human input
+2. Another specific question
+
+**Recommendations:** Based on analysis, suggest options with pros/cons and ask which approach they prefer.
+
+### Contributing Fixes Upstream
+
+When issues are in external dependencies:
+
+```bash
+# 1. Clone the repository
+cd ~/git
+git clone https://github.com/owner/repo.git
+cd repo
+git checkout -b fix/descriptive-name
+
+# 2. Make and commit changes
+git add -A
+git commit -m "Fix: Description
+
+Detailed explanation.
+Fixes #issue-number"
+
+# 3. Fork and push
+gh repo fork owner/repo --clone=false --remote=true
+git remote add fork https://github.com/your-username/repo.git
+git push fork fix/descriptive-name
+
+# 4. Create PR
+gh pr create --repo owner/repo \
+  --head your-username:fix/descriptive-name \
+  --title "Fix: Description" \
+  --body "## Summary
+Description of changes.
+
+Fixes #issue-number"
+```
+
+## Quick Reference
+
+### Daily Monitoring Commands
+
+```bash
+# Check all workflow status
+gh run list --limit 10
+
+# Check for failures
+gh run list --status failure
+
+# View specific failure
+gh run view {id} --log-failed
+
+# Check PR status
+gh pr checks
+
+# Run local quality check
+bash ~/Git/aidevops/.agent/scripts/linters-local.sh
+```
+
+### Common Fix Commands
+
+```bash
+# Dependency issues
+npm ci && npm test
+
+# Linting issues
+npm run lint:fix
+
+# Type issues
+npm run typecheck
+
+# Quality issues
+bash ~/Git/aidevops/.agent/scripts/codacy-cli.sh analyze --fix
+bash ~/Git/aidevops/.agent/scripts/qlty-cli.sh fmt --all
+```