ThothII/docs/agents/issue-tracker.md

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:

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

Read an issue:

gh issue view <number>

List issues:

gh issue list

Add a comment:

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

Apply or remove labels:

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

Close an issue:

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:

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:

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

Then register it as a blocker:

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.