166 lines
3.8 KiB
Markdown
166 lines
3.8 KiB
Markdown
# 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.
|