Skip to content

chore(agents): resolve contributor guidance review gaps #4000

Description

@purp

User Story

I use OpenShell's contributor workflows to review and prepare repository changes. While reviewing PR #3987, I encountered incomplete label discovery and conflicting contribution instructions. I need the follow-up guidance to work consistently for contributors and maintainer agents.

Problem Statement

PR #3987 simplifies contributor guidance, but its bare gh label list commands omit lifecycle labels beyond the default 30 results. Triage no longer explicitly replaces its previous assessment state. Branch naming and verification instructions still disagree across skills and contributor guides, CI.md links to a removed vouch section, and automated dependency PRs have no documented exception to the issue requirement.

Impact / Why This Matters

Agents can miss workflow definitions, retain contradictory assessment states, or follow different branch and verification rules depending on the skill they load. Maintainers currently resolve these inconsistencies manually during review; repeated chat corrections do not fix the repository guidance. Automated dependency PRs also need an explicit issue-linkage exception.

Description

Prepare a focused draft follow-up based on PR #3987. Centralize branch naming in CONTRIBUTING.md, complete label discovery, preserve assessment-state replacement, align verification pointers, repair the vouch link, and document the automated dependency PR exception without changing OpenShell runtime behavior.

Context

Acceptance Criteria

  • Label discovery retrieves the complete current label set and handles missing or ambiguous descriptions without guessing.
  • Triage replaces the prior assessment state while preserving maintainer disposition and unrelated labels.
  • CONTRIBUTING.md defines <type>/<issue>-<description>/<GitHub-username> as the branch naming convention; AGENTS.md, skills, and docs examples agree with it.
  • Documentation and TUI instructions follow scoped verification guidance.
  • Automated dependency PRs are explicitly exempt from separate issues and closing references; human-authored dependency updates retain the normal requirement.
  • CI.md links to the retained vouch instructions.
  • Changed guidance passes applicable formatting and consistency checks.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions