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

Reporting a bug in Semantica AGI requires using the GitHub issue template at .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, 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:

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:

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 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 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}