Metadata-Version: 2.4
Name: issue-assistant
Version: 0.2.1
Summary: Deterministic-first GitHub issue triage engine
License: MIT License
        
        Copyright (c) 2026
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

# Issue Assistant

Issue Assistant is a deterministic GitHub issue triage engine designed for maintainers who want
consistent, explainable signals without automation they can’t trust.

It analyzes GitHub issues and produces **Markdown and JSON artifacts** that help answer:

- Is this issue actionable or missing critical information?
- Does it appear to be a duplicate of existing work?
- How much maintainer effort is likely required?
- Why did the tool reach this conclusion?

All outputs are written to `.issue-assistant/`. Nothing is hidden, guessed, or implicit.

---

## 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+**.

```bash
pip install issue-assistant
```

---

## Run locally

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

---

## GitHub Action

Issue Assistant is available as a GitHub Action:

```yaml
uses: siggmond/issue-assistant@v0.2.0
```

The Action is a thin wrapper around the CLI. You can use the CLI independently or rely
entirely on the Action.

Typical triggers include:

- issue opened / edited / reopened
- scheduled runs (weekly digest)

Artifacts can be uploaded or committed depending on your workflow.

---

## Governance modes

| Mode | Comments | Label suggestions | Intended use |
|------|----------|------------------|--------------|
| dry-run | never | never | analysis only; safest default |
| strict | limited | no | request missing info, flag duplicates |
| aggressive | yes | yes (suggestions) | higher throughput without auto-closing |

Hard constraints:

- issues are never auto-closed
- fixes are never guessed
- maintainer decisions are never overridden

---

## Artifacts generated

A typical run produces:

- ISSUE_SUMMARY.md / issues.json
- MAINTAINER_LOAD.md / maintainer_load.json
- EXPLAINABILITY.md / explainability.json
- per-issue playbooks and explainability JSON

Example outputs are included under `docs/screenshots/`.

---

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