docs: document issue lifecycle labels and roadmap sequencing - #2524
docs: document issue lifecycle labels and roadmap sequencing#2524krishicks wants to merge 1 commit into
Conversation
Add a published Issue Triage and Lifecycle page and align AGENTS.md, CONTRIBUTING.md, README.md, the PR template, and the issue-handling skills on the state:*/agent:* label model. Signed-off-by: Kris Hicks <khicks@nvidia.com>
|
🌿 Preview your docs: https://nvidia-preview-pr-2524.docs.buildwithfern.com/openshell |
| --- | ||
| name: build-from-issue | ||
| description: Given a GitHub issue number, plan and implement the work described in the issue. Operates iteratively - creates an implementation plan, responds to feedback, and only builds when the 'state:agent-ready' label is applied. Includes tests, documentation updates, and PR creation. Trigger keywords - build from issue, implement issue, work on issue, build issue, start issue. | ||
| description: Given a GitHub issue number, plan and implement the work described in the issue. Operates iteratively through a human-controlled agent workflow, planning when `agent:plan-requested` is applied and building only when `agent:implementation-requested` is applied. Includes tests, documentation updates, and PR creation. Trigger keywords - build from issue, implement issue, work on issue, build issue, start issue. |
There was a problem hiding this comment.
I've had a few times where the build-from-issue refuses to work on a ticket because its missing one of these labels. "I won't work on this until label X is applied", which I thought was interesting.
In a way, this system will further encourage that workflow, right? If I try to build-from-issue an issue that doesn't have agent:* applied, should it just fail?
I guess in my mind the challenge comes from manually-controlled agents (e.g me asking codex to implement issue XYZ), and some future automatic-agent that sees the label and auto-picks it up. I'm wondering if there will be a race condition there, where to proceed with my agent, I have to mark the issue, but then in the process of doing so I effectively enqueue the work for our pool of agents.
Not something we have to solve now, but just sharing the pitfalls of how I've used this skill so far
There was a problem hiding this comment.
That's a reasonable concern. I think there's a distinction between an always-on agent that we have watching for labels on issues to take action on and a human directing an agent to do something on an issue. I don't think we want to block the latter. I'll try revising this to account for that distinction.
pimlock
left a comment
pimlock
left a comment
There was a problem hiding this comment.
This looks good IMO, I haven't reviewed all the small changes, my assumption is the overall approach was to define the new process (the issue-lifecycle doc), give that to the agent to update all existing skills/documentation around this?
Once this lands, we'll need to migrate some of the existing labels, right? E.g. the state:... -> agent:....
There was a problem hiding this comment.
Right now, our docs are mostly about how to use openshell. For contributors-like docs we have bunch of .md files (CONTRIBUTING, STYLEGUIDE, etc.).
I can see how this is somewhere in the middle, if I'm a user and want to submit an issue maybe this doc could be useful? However for user submitting an issue, the process should be clear from the github -> new issue, rather than having to review more documentation.
If we wanted to include a page like this, I think this may need a new section, e.g. "Contributing", where we include things like "how to create an issue", but it would probably didn't need all the details in here?
3 participants
Summary
Add a published Issue Triage and Lifecycle page and align AGENTS.md, CONTRIBUTING.md, README.md, the PR template, and the issue-handling skills on the state:/agent: label model.
This is meant to make it easier for us to manage the open issues and PRs in the project. Presently it's not easy to know which issues are validated and/or accepted, for example. This also clarifies the state machine for issues that are going to be owned by an agent.
Related Issue
Changes
Testing
mise run pre-commitpassesChecklist