From 8d95b2ca4f0d42ecc45840ec090edb0121802202 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sondre=20Engebr=C3=A5ten?= <sondre@valdresdronetjenester.no>
Date: Mon, 16 Feb 2026 20:19:25 +0100
Subject: [PATCH] docs(user-guide): add key features, workflow, setup, usage,
 and FAQ

Complete the main user guide with comprehensive coverage of all
GitHub Issues features and workflows.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../github-issues/github-issues-user-guide.md | 365 ++++++++++++++++++
 1 file changed, 365 insertions(+)

diff --git a/guides/github-issues/github-issues-user-guide.md b/guides/github-issues/github-issues-user-guide.md
index 6fd92088..982ee56a 100644
--- a/guides/github-issues/github-issues-user-guide.md
+++ b/guides/github-issues/github-issues-user-guide.md
@@ -94,3 +94,368 @@ Once investigation completes:
 **That's it!** You've gone from GitHub issue to ready-to-build task in 5 minutes.
 
 > **Next:** Learn about [all features](#key-features) or [configure settings](#setup--configuration)
+
+---
+
+## Key Features
+
+### Issue Management
+
+**Import & Browse**
+- Fetch issues from any GitHub repository
+- Filter by status: Open, Closed, or All
+- Pagination for large repositories (50 issues per page)
+- Real-time updates from GitHub
+
+**Issue Details**
+- Full issue view with title, description, and comments
+- Labels, assignees, and milestones
+- Issue metadata (created date, last updated, author)
+- Linked pull requests and commits
+
+### AI-Powered Investigation
+
+**4 Parallel Specialist Agents**
+Each issue investigation runs 4 specialist agents simultaneously:
+
+| Specialist | What It Does | Why It Matters |
+|------------|--------------|----------------|
+| 🔍 **Root Cause Analyzer** | Traces bugs/issues to their source code | Know exactly what to fix |
+| 📊 **Impact Assessor** | Determines affected areas and user impact | Understand the blast radius |
+| 💡 **Fix Advisor** | Suggests concrete solution approaches | Compare options before coding |
+| 🧪 **Reproducer** | Analyzes reproducibility and test coverage | Know if you have test coverage |
+
+**Investigation Report**
+The completed report includes:
+- **Root cause location** - Exact files and line numbers when possible
+- **Impact analysis** - Which features/users are affected
+- **Fix approaches** - Multiple options with pros/cons
+- **Reproducibility** - Can the issue be reproduced? Do tests exist?
+- **Confidence levels** - How certain is each finding?
+
+### Task Creation
+
+**From Investigation to Task**
+One click converts investigation results into an Auto Claude task:
+- All investigation context included automatically
+- Ready for the autonomous build pipeline
+- Maintains link to original GitHub issue
+- Tracked through completion
+
+**Task Context Includes**
+- Investigation findings
+- Relevant code files
+- Related issues/PRs
+- Repository context
+
+### GitHub Integration
+
+**Post Findings**
+Share investigation results directly to GitHub:
+- Post investigation report as a comment
+- Update issue labels
+- Close issues after resolution
+
+**Activity Tracking**
+Every issue tracks:
+- Investigation history
+- Task creation events
+- Resolution status
+- Comments posted back to GitHub
+
+---
+
+## Integration Workflow
+
+The GitHub Issues integration follows a simple pipeline from issue to completed work:
+
+```
+┌─────────────────┐
+│  Import Issue   │
+│  from GitHub    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   Investigate   │
+│   with AI       │
+│  (4 specialists)│
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Create Task    │
+│  in Auto Claude │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Implement      │
+│  (autonomous    │
+│   pipeline)     │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│    Merge &      │
+│   Close Issue   │
+└─────────────────┘
+```
+
+### Stage Details
+
+**1. Import Issue**
+- Fetch from GitHub repository
+- View with all context (comments, labels, metadata)
+- Select based on priority, labels, or assignment
+
+**2. Investigate with AI**
+- 4 specialists analyze in parallel
+- Root cause, impact, fix options, reproducibility
+- Comprehensive report in minutes
+
+**3. Create Task**
+- One-click task creation
+- All investigation context included
+- Ready for autonomous build pipeline
+
+**4. Implement**
+- Auto Claude agents plan and implement
+- Code review and QA validation
+- All within isolated git worktree
+
+**5. Merge & Close**
+- Semantic merge back to main branch
+- Update GitHub issue
+- Close issue when complete
+
+> This workflow keeps your main branch safe while autonomous agents work in isolated environments.
+
+---
+
+## Setup & Configuration
+
+### GitHub Authentication
+
+Auto Claude uses GitHub CLI for secure authentication:
+
+**Step 1: Install GitHub CLI**
+```bash
+# macOS
+brew install gh
+
+# Windows
+winget install --id GitHub.cli
+
+# Linux
+# See https://github.com/cli/cli#installation
+```
+
+**Step 2: Authenticate**
+```bash
+gh auth login
+```
+
+Follow the prompts:
+1. Choose **GitHub.com**
+2. Choose **HTTPS**
+3. Choose **Login with a web browser**
+
+**Step 3: Verify**
+```bash
+gh auth status
+```
+
+You should see your GitHub account information.
+
+### Connect a Repository
+
+1. Open Auto Claude
+2. Create or open a project
+3. Go to **Project Settings → GitHub Integration**
+4. Click **"Connect Repository"**
+5. Enter repository in `owner/repo` format: `AndyMik90/Auto-Claude`
+6. Click **"Connect"**
+
+Auto Claude verifies access and loads repository metadata.
+
+### Investigation Settings
+
+Go to **Project Settings → GitHub Integration → AI Investigation**:
+
+**Fast Mode (Optional)**
+- Toggle **"Enable Fast Mode"** for 2.5x faster investigations
+- Uses premium Opus 4.6 pricing
+- Best for: Time-critical investigations, large codebases
+
+**Model Selection**
+- **Standard Mode:** Balanced speed and cost
+- **Fast Mode:** Faster investigations, different pricing
+- Auto Claude switches automatically if you hit rate limits
+
+> **Note:** See [Advanced AI Configuration](github-issues-advanced-ai-configuration.md) for details on pricing and performance tuning.
+
+---
+
+## Using the Features
+
+### Importing & Browsing Issues
+
+**Fetch Issues**
+1. Navigate to **GitHub Issues** in the sidebar
+2. Click **"Fetch Issues"**
+3. Select filter: Open, Closed, or All
+4. Issues load with pagination (50 per page)
+
+**Filter & Search**
+- Use the filter dropdown to switch between Open/Closed/All
+- Scroll to load more pages automatically
+- Click any issue to view details
+
+**Issue Detail View**
+- Title and description
+- All comments (chronological)
+- Labels, assignees, milestones
+- Metadata (created, updated, author)
+- Linked pull requests and commits
+
+### Running AI Investigations
+
+**Start an Investigation**
+1. Open any issue from the list
+2. Review the issue details
+3. Click the **"Investigate"** button
+
+**Investigation Progress**
+Watch as 4 specialist agents run in parallel:
+- Each specialist shows progress in real-time
+- Terminal output shows agent thinking
+- Estimated time remaining updates continuously
+
+**Investigation Results**
+When complete, the report shows:
+- **Root Cause** - What's causing the issue, where it is
+- **Impact** - What's affected, who's impacted
+- **Fix Options** - Multiple approaches with pros/cons
+- **Reproducibility** - Can it be reproduced? Test coverage
+- **Confidence** - How certain is each finding?
+
+> **Tip:** Results vary by issue type. Bugs get detailed root causes; feature requests get architectural analysis.
+
+### Creating Tasks from Results
+
+**Create a Task**
+1. Review the investigation report
+2. Click **"Create Task"**
+3. Confirm task details (auto-populated from investigation)
+4. Task appears in your Auto Claude task list
+
+**What's Included**
+- Investigation findings
+- Relevant code files and context
+- Link to original GitHub issue
+- Implementation suggestions from the Fix Advisor
+
+**Next Steps**
+The task is now ready for Auto Claude's autonomous pipeline:
+- Planner agent breaks it into subtasks
+- Coder agents implement the solution
+- QA agents validate the work
+- You review and merge
+
+### Posting Findings to GitHub
+
+**Share Results**
+1. After investigation completes, click **"Post to GitHub"**
+2. Choose what to include:
+   - Full investigation report
+   - Summary only
+   - Custom message
+3. Click **"Post"** to add as a comment
+
+**Update Issue Status**
+- Add labels based on investigation findings
+- Close issue if resolved
+- Link related tasks
+
+**Activity Tracking**
+All GitHub interactions are tracked:
+- Comments posted
+- Labels added
+- Issues closed
+- Timestamps for each action
+
+---
+
+## FAQ
+
+### General
+
+**Q: Do I need a GitHub account?**
+A: Yes, you need a GitHub account with access to the repositories you want to investigate.
+
+**Q: Does this work with private repositories?**
+A: Yes, as long as your GitHub account has access to the private repository.
+
+**Q: Can I investigate issues from any repository?**
+A: Yes, any repository you have access to—your own repos, organization repos, or public repos.
+
+### Investigation
+
+**Q: How long does an investigation take?**
+A: Typically 2-5 minutes for standard mode, 1-2 minutes with Fast Mode enabled. Complex issues may take longer.
+
+**Q: What if the investigation doesn't find a root cause?**
+A: The specialists report their confidence levels. Low confidence means more context is needed—try again after providing more information or reproduction steps.
+
+**Q: Can I run multiple investigations at once?**
+A: Yes, you can investigate multiple issues simultaneously. Each investigation runs independently with its own specialists.
+
+**Q: Do investigations use my API quota?**
+A: GitHub API calls are minimal (fetching issues). The heavy lifting is done by Auto Claude's AI agents, which use your Claude API subscription or configured profiles.
+
+### Tasks & Implementation
+
+**Q: Do I have to create a task after investigating?**
+A: No, you can investigate just to understand the issue. Task creation is optional.
+
+**Q: Can I edit the task before starting the build?**
+A: Yes, the task is fully editable. You can modify the description, add requirements, or adjust the scope.
+
+**Q: What happens to the task after implementation?**
+A: The task goes through QA validation, then you review the changes before merging to your main branch.
+
+### Troubleshooting
+
+**Q: "Failed to fetch issues" error**
+A: Check that:
+- GitHub CLI is authenticated (`gh auth status`)
+- Your repository URL is correct
+- You have access to the repository
+
+**Q: Investigation stuck at "Starting..."**
+A: This usually means:
+- Claude API is unreachable (check your connection)
+- Rate limit hit (Auto Claude switches accounts automatically)
+- Check Settings → Claude Profiles for account status
+
+**Q: Results seem inaccurate**
+A: Investigation quality depends on:
+- Issue description quality (be specific!)
+- Codebase accessibility
+- Reproduction steps (if known)
+Try providing more context and re-investigate.
+
+---
+
+## Next Steps
+
+**For most users:** You're ready to go! Start investigating issues.
+
+**For technical users:** See [Advanced AI Configuration](github-issues-advanced-ai-configuration.md) to optimize performance and costs.
+
+**For developers:** See [Customization Guide](github-issues-customization-guide.md) to extend and customize the integration.
+
+---
+
+**Need help?** Join the [Auto Claude community](https://github.com/AndyMik90/Auto-Claude/discussions) or report issues [on GitHub](https://github.com/AndyMik90/Auto-Claude/issues).