# How to Report a Bug or Issue in AI Berkshire: Complete GitHub Workflow

> Learn how to report a bug or issue in ai-berkshire using GitHub Issues. Follow our guide for templates, reproducible examples, and efficient diagnostics to improve the AI model.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: how-to-guide
- Published: 2026-07-08

---

**Use GitHub Issues with one of the three provided templates—Skill error, Data error, or Suggestion—and include a concrete, reproducible example with your model version and exact command to ensure maintainers can diagnose the problem efficiently.**

The xbtlin/ai-berkshire repository uses GitHub Issues as the official channel for bug reports, data-error notices, and improvement suggestions. Whether you encounter broken prompt workflows or incorrect financial data, following the structured reporting process ensures your issue gets addressed quickly. This guide covers the exact steps to report a bug or issue in ai-berkshire, referencing the contributing guidelines and security protocols implemented in the source code.

## Choose the Correct Issue Template

The repository provides three distinct templates located in `.github/ISSUE_TEMPLATE/` to categorize your report:

### 🐞 Skill Error

Use this template for broken prompts, workflow failures, or output-format problems in the AI skills.

### 📉 Data Error

Use this template for incorrect price, market-cap, or financial numbers returned by the system.

### 💡 Suggestion

Use this template for concrete improvement ideas or feature requests.

## Required Fields for Reproducible Reports

According to [`CONTRIBUTING.md`](https://github.com/xbtlin/ai-berkshire/blob/main/CONTRIBUTING.md) (lines 30-38), every claim in your report needs a **concrete, reproducible example**. When filling out your issue, include:

- **Skill name** (e.g., `/investment-research`)
- **Full command** you ran (including ticker or parameters)
- **Exact error message** or description of wrong output
- **Model and client version** (Claude Code or Codex version)
- **Step-by-step reproduction** instructions so maintainers can replicate the issue
- **Optional**: Screenshots, logs, or minimal reproducible examples

## How to Submit an Issue on GitHub

1. Navigate to the **xbtlin/ai-berkshire** repository on GitHub
2. Click **Issues** → **New Issue**
3. Select the appropriate template from the three options
4. Fill in all required fields from the template
5. Click **Submit new issue**

## Reporting Security Vulnerabilities

For security-related bugs such as leaked API keys or prompt-injection flaws, **do not post publicly**. Instead, follow the private reporting procedure detailed in [`SECURITY.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SECURITY.md) (lines 9-12).

## Example: Creating an Issue via GitHub CLI

You can automate bug report creation using the GitHub CLI:

```bash

# Example: creating a bug report from the command line with GitHub CLI

# (install gh first: https://cli.github.com/)

gh issue create \
  --title "🐞 /investment-research fails on PDD with Claude‑3.5‑Sonnet" \
  --label "bug" \
  --body "$(cat <<EOF
**Skill**: /investment-research
**Command**: /investment-research PDD
**Model**: Claude‑3.5‑Sonnet (Claude Code)
**Client version**: claude‑code 2.1.0
**Error**: `ToolError: WebSearch not permitted – permission denied`
**Steps to reproduce**
1. Run the command above in a fresh terminal.
2. Observe the permission error.
**Expected**: the skill should invoke WebSearch, fetch the latest financial data and return a full report.
**Actual**: the skill aborts before any data retrieval.
**Additional context**
- OS: macOS 14.5
- Python 3.11.9 (used by the underlying tool scripts)
EOF
)"

```

## Example: Filled-In Issue Template

When using the "🐞 Skill error" template, your issue body should look like this:

```markdown
**Skill:** `/investment-research`  
**Command:** `/investment-research PDD`  
**Model / client:** Claude‑3.5‑Sonnet, `claude-code` 2.1.0  
**Error message:**  

```

ToolError: WebSearch not permitted – permission denied

```  
**Reproduction steps**  
1. Open a new terminal.  
2. Run the command exactly as shown.  
3. The skill aborts with the error above.  

**Expected behavior**  
The skill should call `WebSearch`, retrieve recent earnings data, and produce the full multi‑master report.  

**Actual behavior**  
The skill stops before any data is fetched.  

**Additional info**  
- Running the same command with the `codex` client works fine.  
- The repository is cloned at `~/ai-berkshire`.  
- No custom `.claude/settings.local.json` overrides are present.  

```

## Summary

- The xbtlin/ai-berkshire repository uses **GitHub Issues** as the official bug reporting channel, as referenced in [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) and [`CONTRIBUTING.md`](https://github.com/xbtlin/ai-berkshire/blob/main/CONTRIBUTING.md)
- Choose from three templates located in `.github/ISSUE_TEMPLATE/`: Skill error (🐞), Data error (📉), or Suggestion (💡)
- Include a **concrete, reproducible example** as required by [`CONTRIBUTING.md`](https://github.com/xbtlin/ai-berkshire/blob/main/CONTRIBUTING.md) (lines 30-38)
- Report security vulnerabilities privately via [`SECURITY.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SECURITY.md) (lines 9-12) instead of public issues
- Always provide your skill name, exact command, model/client version, and error message

## Frequently Asked Questions

### Where are the issue templates stored in ai-berkshire?

The issue templates are located in the `.github/ISSUE_TEMPLATE/` directory at the repository root. This directory contains the markdown templates that pre-populate the GitHub issue form when you select 🐞 Skill error, 📉 Data error, or 💡 Suggestion.

### What constitutes a concrete reproducible example according to the contributing guide?

According to [`CONTRIBUTING.md`](https://github.com/xbtlin/ai-berkshire/blob/main/CONTRIBUTING.md) (lines 30-38), a concrete reproducible example must include your exact skill name, the full command you ran with parameters, the specific error message or wrong output, your model and client version, and step-by-step instructions that allow maintainers to run the same command and observe the same behavior.

### How should I report a security bug in ai-berkshire?

Do not open a public GitHub issue for security-related bugs. Instead, follow the private reporting procedure described in [`SECURITY.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SECURITY.md) (lines 9-12). This applies to vulnerabilities like leaked API keys, prompt-injection flaws, or any issue that could compromise user security if disclosed publicly.

### Can I create issues programmatically without using the GitHub web interface?

Yes. You can use the GitHub CLI (`gh`) to create issues from the command line, specifying the title, labels, and body content. This approach is useful for automating bug reports or integrating with your development workflow, as demonstrated in the example above using `gh issue create`.