Labels
GAIA’s labels give every issue the same few facts: what kind of work it is, how urgent, how hard, and whether someone has it. /gaia-debt uses them to decide what to fix first, and anyone on the team can see the state of an issue at a glance. The labels are all defined in one file, .gaia/labels.json. gaia labels sync creates the labels your repository is missing and renames labels whose names changed, so every issue keeps its label. It also updates a label’s description to match GAIA’s. When a label’s color differs from GAIA’s, it tells you instead of overwriting your color.
/setup-gaia and /update-gaia run the sync. To run it at any other time, ask Claude:
Sync GAIA's GitHub labels. Show me what would change first.To replace your own label colors with GAIA’s, say so in the same request. A label of your own that GAIA does not define is left in place: the sync reports it and never removes it. To create one, ask Claude. It adds the label on GitHub and leaves .gaia/labels.json as GAIA’s list, so updates never merge against it. If your GitHub account is not allowed to edit labels, the sync prints the gh label commands instead, for someone who has that permission, such as a repository admin, to run.
Tech debt
Section titled “Tech debt”| Label | Meaning |
|---|---|
| tech-debt | A review finding outside the pull request’s scope, saved to be fixed later by /gaia-debt |
| severity:critical | Wrong, or will produce broken work; fixed first |
| severity:major | A significant gap or defect; fixed before minor findings |
| severity:minor | Real but small; fixed by default, never skipped |
| severity:investigate | Severity not known yet; needs research before it can be graded |
| difficulty:easy | The issue text and the code it points to make the fix clear |
| difficulty:medium | The fix needs a design decision, and the surrounding code shows which way to go |
| difficulty:hard | The fix needs a design decision the surrounding code does not answer |
| footprint:narrow | One piece of code in one file, with no change to how other code calls it |
| footprint:wide | Touches several files, changes how other code calls it, or changes the structure |
| footprint:spec | Needs a design SPEC first; fixed through /gaia-spec |
| debt:spec-pending | Handed to /gaia-spec; on hold until the SPEC starts |
| debt:spec-active | A SPEC is in progress for this issue, or is keeping it open until a recorded condition is met |
Every issue carries tech-debt, a severity, and a footprint. A difficulty is added only when the filer read the cited code, so an issue without one is normal. At most three severity:investigate issues can be open at once. When three are open, Claude does not file a fourth as investigate: it grades that finding itself from the code, or resolves one of the open ones first by answering its question and re-grading it (how).
Work in progress
Section titled “Work in progress”| Label | Meaning |
|---|---|
| in-progress | Someone is working on this issue right now; do not pick it up. Added when the issue is claimed and removed when the pull request that closes it merges, when Claude closes that pull request unmerged, or when you tell Claude the work is dropped. |
| needs-human | An automated process stopped here; a person needs to review it. |
Issue types
Section titled “Issue types”| Label | Meaning |
|---|---|
| bug | Existing behavior is broken or wrong |
| enhancement | A new feature or request |
| documentation | Improvements or additions to documentation |
| security | A security defect or dependency CVE. Created only when .github/dependabot.yml exists. |
| wontfix | Deliberately declined; do not file it again. When a finding matches an issue with this label, it is not filed as tech debt again. |
| dependencies github_actions | Dependabot (opens in a new tab)’s own labels |
Why these colors
Section titled “Why these colors”The colors follow one rule: warm colors (red, orange, yellow) mean something needs attention, and every other label uses a cool or neutral color. A glance at an issue list then shows what needs you before you read a single label.
- Severity is one red ramp, lightest for severity:minor and darkest for severity:critical, so the grades read as a group. severity:investigate sits outside the ramp in a muted rose, because its severity is not known yet.
- Red belongs to severity and security. That is why bug is magenta, not red.
- in-progress is bright yellow, a color no other label uses, so a claimed issue stands out. It is not green, because green reads as “done” when the label means “being worked on right now”.
- needs-human is orange: a person has to act.
- The grading labels are cool ramps that darken as the work grows: teal for difficulty, from difficulty:easy to difficulty:hard, and purple for footprint, from footprint:narrow to footprint:spec.
- The SPEC hand-off is green, lighter while debt:spec-pending waits and darker once debt:spec-active is under way.
- tech-debt and wontfix are neutral gray. They say what an issue is, not how urgent it is.
If you recolor a label in your repository, the sync keeps your color and only reports the difference (see the top of this page).
Not created
Section titled “Not created”GAIA never creates GitHub’s default good first issue and help wanted labels: they invite one-off contributions from people who do not know the background of the work. If your repository already has them, the sync reports them as blocked but present and leaves them in place.