Skip to content

Label color-coding + HANDOFF.md workflow update markdown #60

Description

@MeatPopSci1972

Label color-coding + HANDOFF.md workflow update

Part of Issue Contracts (umbrella: #57 ).
Depends on **Issues #58 and #59 ** being complete.

Context

Routing labels (rfc, for_cowork, for_session, regression, hotfix) now carry contracts. They direct AI engagement mode. Visual reinforcement in the GitHub UI helps humans scan the backlog at a glance and reinforces the contract meaning.

This issue also updates HANDOFF.md to document the full AI workflow (verify → knowledge → plan) now that both endpoints exist.

Color mapping

Consistent with common conventions (red = stop/urgent, green = go, yellow = caution, purple = design):

Label Color Hex Meaning
regression Red #d73a4a Drop everything
hotfix Red #d73a4a Drop everything
rfc Purple #7057ff Design spike — think first
for_cowork Green #0e8a16 Ready to execute
for_session Yellow #fbca04 Discussion required
next-priority Dark blue #0052cc Owner-designated priority
icebox Gray #e6e6e6 Parked
architecture Light purple #c5b6ff Cross-cutting design
server Dark gray #333333 Ops/infrastructure
ui Cyan #1d76db User-facing rendering
tests Light green #b4e59c Test infra
tour Orange #ff8c00 Onboarding feature
accessibility Pink #ff69b4 a11y concern
external-assets Brown #8b4513 Assets fetched at runtime
store Navy #1a3a7c Store/state layer

HANDOFF.md updates

FIRST ACTIONS section

Add steps 6 and 7:

6. Before planning any issue, run `GET /verify-issue?number=N`. 
   If `ready_to_plan: false`, address errors. If warnings present, 
   acknowledge with user before proceeding.

7. After green verification, run `GET /knowledge?labels=<labels>` 
   (using labels from verify response). Apply principles returned.

DEV SERVER API table

Add rows:

| /verify-issue?number=N | Label-keyed verification + mode derivation |
| /knowledge?labels=X,Y  | Label-keyed principle retrieval            |

Issue Contracts section (new)

Add a new top-level section documenting:

  • What an Issue Contract is (the four layers)
  • The five routing labels and their modes
  • How color coding reinforces contract meaning
  • Link to the umbrella issue

Steps

  1. Apply colors via gh label edit for each label in the mapping table
  2. Update HANDOFF.md FIRST ACTIONS with steps 6 and 7
  3. Update HANDOFF.md DEV SERVER API table with new endpoints
  4. Add Issue Contracts section to HANDOFF.md
  5. Commit HANDOFF.md changes
  6. Verify colors render correctly in GitHub UI (screenshot attached to issue)

Done when

  • All labels in the color mapping table updated to specified hex values
  • HANDOFF.md FIRST ACTIONS includes steps 6 and 7
  • HANDOFF.md DEV SERVER API table includes both new endpoints
  • HANDOFF.md has a dedicated "Issue Contracts" section
  • Screenshot of issue list with new colors attached to this issue for verification

Do not touch

  • Any code files (this is documentation + GitHub API only)
  • Label names (colors only; names are stable)
  • Issue bodies (this issue doesn't relabel or re-triage anything)

Out of scope

  • Auto-applying labels based on content
  • Bulk re-triage of existing issues
  • Renaming labels

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

    choreHygiene, rename, cleanupdocumentationImprovements or additions to documentationfor_coworkAutonomous execution ready — Cowork can run thisiceboxParked — not current cycle

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions