# How to Report a Bug in Semantica AGI: A Complete Guide

> Learn how to report a bug in Semantica AGI using the GitHub issue template. Provide a minimal reproducible example and environment details for efficient bug fixing.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-13

---

**Reporting a bug in Semantica AGI requires using the GitHub issue template at [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/semantica-agi/semantica/blob/main/.github/ISSUE_TEMPLATE/bug_report.md) and providing a minimal reproducible example with environment details.**

The Semantica AGI repository (`semantica-agi/semantica`) provides a structured workflow for submitting bug reports that helps maintainers reproduce and resolve issues efficiently. Understanding how to report a bug in Semantica AGI ensures your issue gets triaged quickly and reduces the back-and-forth typically required for diagnosis.

## Access the Official Bug Report Template

Navigate to the repository's **Issues** tab and select **"New Issue" → "Bug report"**. This automatically loads the structured template located at [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/semantica-agi/semantica/blob/main/.github/ISSUE_TEMPLATE/bug_report.md), which enforces consistent formatting across all reports.

The template pre-populates several required sections that you must complete before submission. Do not delete these headers—maintainers rely on them during triage.

## Document the Required Sections

Complete every mandatory field in the template to ensure maintainers can reproduce your issue:

- **Bug Description** – Summarize the problem in one or two sentences, focusing on the specific component (e.g., `ContextGraph.record_decision()`).

- **Steps to Reproduce** – List exact commands or API calls that trigger the bug. Include specific methods like `semantica doctor` or `graph.record_decision(...)` with precise arguments.

- **Expected vs. Actual Behavior** – Clearly state what functionality you expected and what actually occurred, including any error messages.

- **Environment** – Specify your operating system, Python version, Semantica version, and installation method. Behavior often differs across platforms, making this data critical for reproduction.

- **Code Example** – Provide a minimal, self-contained snippet that demonstrates the issue (see example below).

- **Error Messages / Logs** – Paste the complete traceback or log output without truncation.

Optional fields include screenshots, related issues or pull requests, and proposed solutions.

## Include a Minimal Reproducible Example

Supply a concise code block that isolates the bug. For instance, when reporting a type validation issue in the decision-recording API:

```python
from semantica.context import ContextGraph

# Create a graph with advanced analytics enabled

graph = ContextGraph(advanced_analytics=True)

# Intentional misuse: passing an unsupported type to `confidence`

decision_id = graph.record_decision(
    category="credit_application",
    scenario="Personal loan, $85k income, 31% DTI, 3yr employment",
    reasoning="Income meets threshold; employment stable",
    outcome="proceed_to_underwriting",
    confidence="high",   # <-- should be a float, not a string

)

```

When executed with Semantica 0.6.5 on Python 3.11, this produces the following traceback that you should include in the "Error Messages / Logs" section:

```text
Traceback (most recent call last):
  File "example.py", line 12, in <module>
    confidence="high",
  File ".../semantica/context.py", line 254, in record_decision
    raise TypeError("confidence must be a float")
TypeError: confidence must be a float

```

## Follow the Contribution Guidelines

Before submitting, review [`CONTRIBUTING.md`](https://github.com/semantica-agi/semantica/blob/main/CONTRIBUTING.md) in the repository root, specifically the **Bug Reports** section. This document outlines workflow expectations, including:

- Commenting on existing issues before starting work
- Waiting for maintainer assignment
- Referencing issues in pull request descriptions (e.g., `Closes #123`)

Adhering to these guidelines ensures your report aligns with the project's triage process and maintainer expectations.

## Submit and Follow Up

After completing the template, click **"Submit new issue"**. The repository automation automatically tags your submission with the `bug` label and routes it to the appropriate maintainers.

Monitor the issue for requests for additional information. If you develop a fix, open a pull request that references the original issue number to maintain traceability.

## Summary

- Use the [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/semantica-agi/semantica/blob/main/.github/ISSUE_TEMPLATE/bug_report.md) template to ensure consistent formatting
- Provide environment details (OS, Python version, Semantica version) for platform-specific issues
- Include a minimal code example that reproduces the error
- Reference the [`CONTRIBUTING.md`](https://github.com/semantica-agi/semantica/blob/main/CONTRIBUTING.md) guidelines for workflow expectations
- Submit the issue and respond promptly to maintainer requests for clarification

## Frequently Asked Questions

### Where is the bug report template located in the Semantica AGI repository?

The template resides at [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/semantica-agi/semantica/blob/main/.github/ISSUE_TEMPLATE/bug_report.md). Selecting "Bug report" when creating a new issue automatically loads this template with all required fields pre-populated.

### What information is absolutely required when reporting a bug?

You must provide a bug description, steps to reproduce, expected versus actual behavior, environment specifications (OS, Python version, Semantica version), a minimal code example, and full error logs or tracebacks.

### How do I submit a fix for a bug I reported?

After creating the issue, wait for triage or comment indicating you intend to work on it. Once approved, create a branch, implement your fix, and open a pull request that references the issue with keywords like `Closes #123` or `Fixes #123`.

### What should I do if I cannot reproduce the bug consistently?

Document the intermittent behavior in the "Steps to Reproduce" section, noting the frequency (e.g., "occurs 1 in 5 runs") and any environmental factors that might influence the behavior. Include relevant logs from both successful and failed executions to help maintainers identify race conditions or state-dependent issues.