# Issue tracker: GitHub

Issues and specifications for this repository live in GitHub Issues under
`mptyl/ThothII`.

Use the GitHub CLI (`gh`) for issue operations. Infer the repository from the
current Git remote when possible.

## Conventions

Create an issue:

```bash
gh issue create --title "<title>" --body-file <file>
```

Read an issue:

```bash
gh issue view <number>
```

List issues:

```bash
gh issue list
```

Add a comment:

```bash
gh issue comment <number> --body-file <file>
```

Apply or remove labels:

```bash
gh issue edit <number> --add-label "<label>"
gh issue edit <number> --remove-label "<label>"
```

Close an issue:

```bash
gh issue close <number>
```

## Pull requests as a triage surface

Pull requests are not used as the primary request or triage surface.

A pull request may implement or resolve an issue, but the issue remains the
canonical location for:

- the request;
- its scope and acceptance criteria;
- triage status;
- dependencies and sub-issues;
- implementation progress;
- the final resolution summary.

## Publishing work

When a workflow or skill says to publish a plan, specification, finding, or
request, create or update a GitHub issue.

Do not leave the only authoritative copy in a chat transcript.

Long implementation documents may also be committed to the repository. In that
case, the corresponding issue should link to the committed document and track
its execution status.

## Fetching work

When a workflow or skill refers to an issue number, retrieve the current issue
and its comments before acting:

```bash
gh issue view <number> --comments
```

Treat the live issue state as authoritative for assignment, labels, closure,
and subsequent decisions.

## Wayfinding operations

A wayfinding map is represented by a parent GitHub issue and, when useful,
smaller child issues.

### Map

Create or update one parent issue describing:

- the intended outcome;
- relevant context;
- known constraints;
- the proposed decomposition;
- dependencies between tasks;
- completion criteria.

Label it according to `docs/agents/triage-labels.md`.

### Child issues

Create a separate issue for each independently actionable unit of work.

Keep the parent issue readable: summarize the decomposition there and link the
child issues instead of copying every implementation detail.

When GitHub sub-issues are available, register the relationship through the
GitHub API. Otherwise, maintain a checklist of linked child issues in the
parent issue.

### Dependencies

Represent blocking relationships with GitHub's native issue-dependency API
when available.

First obtain the database ID of the blocking issue:

```bash
gh api repos/mptyl/ThothII/issues/<blocking-number> --jq '.id'
```

Then register it as a blocker:

```bash
gh api \
  --method POST \
  repos/mptyl/ThothII/issues/<blocked-number>/dependencies/blocked_by \
  -F issue_id=<blocking-issue-database-id>
```

If native dependencies are unavailable, record the relationship explicitly in
both issues.

### Frontier

The frontier is the set of open child issues that:

- have no unresolved blockers;
- are sufficiently specified;
- can be worked on independently;
- are not already being worked on.

Use labels and current issue relationships to identify the frontier.

### Claim

Before starting an issue:

1. confirm that it is still open and unblocked;
2. assign it to the current operator when appropriate;
3. apply the label `ready-for-agent` only if it is genuinely executable;
4. add a short comment stating that work has started.

### Resolve

When the work is complete:

1. verify the issue's acceptance criteria;
2. add a concise resolution comment with relevant files, tests, or decisions;
3. update the parent issue or dependent issues;
4. close the issue;
5. reconsider the frontier, because resolving a blocker may unlock more work.