Issue Assistant

Issue Assistant is a deterministic GitHub issue triage engine for maintainers who need consistent, explainable signals about issue quality, duplicates, actionability, and maintainer load.

It is designed to reduce triage burden without taking control away from humans. It is not an auto-closing bot, not an LLM-based subjective classifier, and not hidden automation. Every output is a Markdown or JSON artifact that can be inspected, reviewed, and ignored.

All generated artifacts are written to .issue-assistant/ by default. Nothing is hidden, guessed, or implicit.

---

Quick Reviewer Path

Use this path to understand the project in about five minutes:

• Problem solved: Issue Assistant gives maintainers deterministic, explainable triage signals for noisy, incomplete, duplicate, or high-load GitHub issues.
• Install the CLI: pip install issue-assistant
• Run locally: issue-assistant analyze --github-token "$GITHUB_TOKEN" --repo owner/name --output-dir .issue-assistant --governance-mode dry-run
• Run safely: --governance-mode dry-run writes artifacts only and does not comment, label, or close issues.
• Artifacts: Outputs are written under .issue-assistant/, including summary Markdown, JSON data, and per-issue files under .issue-assistant/issues/<issue_number>/.
• GitHub Action: action.yml is a thin wrapper around the CLI. It installs issue-assistant, runs issue-assistant analyze, then uploads, commits, or skips artifacts based on the publish input.
• Rules and explainability: Rule-based signals live in src/issue_assistant/phases/. Artifact writing is in src/issue_assistant/artifacts.py, and governance-aware comment decisions are in src/issue_assistant/automation.py.
• Governance modes: dry-run is artifact-only, strict allows limited transparent comments when configured, and aggressive can include label suggestions while still preserving maintainer control.
• Tests and checks: The repo includes pytest tests under tests/ and a pytest.ini configuration.

---

What This Project Proves

Issue Assistant demonstrates:

• deterministic CLI product design
• GitHub issue triage automation built around maintainer review
• explainable rule-based analysis instead of opaque scoring
• Markdown and JSON artifact generation for auditability
• GitHub Action integration through a composite action wrapper
• governance-aware automation modes with dry-run as the safe default
• duplicate, actionability, quality, and maintainer-load signals where implemented
• human-first automation boundaries that support decisions without making final decisions
• open-source maintainer workflow awareness, including issue-triggered and scheduled runs

---

Why This Exists

Maintainers spend a disproportionate amount of time triaging issues that are:

• missing reproduction steps, logs, or environment details
• duplicates that fragment discussion
• unclear about expected vs. actual behavior
• noisy or low-signal

Issue Assistant provides a deterministic baseline for triage so humans can make faster, more consistent decisions without surrendering control.

---

Design Principles

Issue Assistant is intentionally conservative:

• Deterministic only: no LLMs, no probabilistic output
• Explainable by construction: every outcome maps to rules and evidence
• Governance-aware: safe defaults, no surprise side effects
• Human-first: maintainers always make the final call

If a signal cannot be explained clearly, it does not exist.

---

Installation

Requires Python 3.10+.

pip install issue-assistant

---

Run Locally

issue-assistant analyze \
  --github-token "$GITHUB_TOKEN" \
  --repo owner/name \
  --output-dir .issue-assistant \
  --governance-mode dry-run

This performs a full analysis and writes artifacts locally without modifying issues.

You can also analyze an exported Issues API-style payload:

issue-assistant analyze \
  --issues-file issues.json \
  --output-dir .issue-assistant \
  --governance-mode dry-run

---

GitHub Action

Issue Assistant is available as a GitHub Action. Pin to an existing tag or commit SHA:

uses: siggmond/issue-assistant@v0.2.1

The Action is a thin wrapper around the CLI. It installs the issue-assistant package, runs issue-assistant analyze, and publishes artifacts according to the publish input.

Typical triggers include:

• issue opened, edited, or reopened
• scheduled runs for repo-wide review or weekly digest artifacts

Artifacts can be uploaded, committed, or skipped depending on your workflow.

---

Governance and Safety Boundaries

Dry-run is the safest default and should be the first mode reviewers try.

Mode	Comments	Label suggestions	Intended use
dry-run	never	never	analysis only; writes artifacts without issue side effects
strict	limited, if --auto-comment is enabled	no	request missing information or flag likely duplicates transparently
aggressive	yes, if --auto-comment is enabled	suggestions only	higher-throughput triage support without auto-closing

Hard constraints:

• no issue auto-close
• no guessed fixes
• no invisible scoring
• no hidden side effects
• comments and label suggestions must be traceable to deterministic rules
• maintainer decisions are never overridden

---

Artifacts Generated

A typical run writes artifacts under .issue-assistant/, including:

• ISSUE_SUMMARY.md and issues.json
• DUPLICATES.md and DUPLICATE_GROUPS.md
• TRIAGE.md
• MAINTAINER_ACTIONS.md
• MAINTAINER_COST.md
• MAINTAINER_LOAD.md and maintainer_load.json
• EXPLAINABILITY.md and explainability.json
• per-issue playbooks, contributor guides, label suggestions, quality breakdowns, and explainability JSON under .issue-assistant/issues/<issue_number>/

Example Markdown outputs are included under docs/. Existing screenshots live under docs/screenshots/.

---

Current Scope / Honest Limitations

Issue Assistant is deterministic and conservative by design.

• It does not auto-close issues.
• It does not guess fixes.
• It does not replace maintainer judgment.
• Duplicate detection and actionability signals are rule-based and best-effort.
• Repositories with unusual issue templates, support flows, or domain-specific formats may need configuration or manual review.
• Generated artifacts support human decisions; they are not final decisions.

---

When Not To Use This Tool

Issue Assistant is not a good fit if you want:

• fully automated triage or auto-closing
• subjective or sentiment-based analysis
• invisible automation
• zero repository artifacts

---

Philosophy

Explainability is a core invariant.

If the tool cannot explain why it produced an output, that output should not exist.

Contributing

Issues, suggestions, and pull requests are welcome. This project is intentionally scoped around explainable maintainer support, so changes should preserve deterministic behavior and human review boundaries.