Labeling Guide
This document describes the labeling system used for issues and PRs in pinchtab. Use this guide when triaging tickets or asking agents to review open issues.
Quick Reference
Every issue should have:
- Exactly one Type label (bug, enhancement, documentation, question, etc.)
- One Status label (ready, in-progress, blocked, fixed-unreleased, needs-investigation)
- One Priority label (high, medium, low) — optional for documentation or questions
Tier 1: Issue Type (Mandatory)
Choose exactly one:
| Label | Color | Usage |
|---|---|---|
bug |
🔴 Red | Something isn't working correctly |
enhancement |
🔵 Cyan | New feature or capability request |
documentation |
🔵 Blue | Improvements/additions to README, docs, or code comments |
question |
🟣 Purple | Request for clarification or information |
good first issue |
🟣 Purple | Good for newcomers (in addition to type label) |
help wanted |
🟢 Green | Needs extra attention or expertise |
dependencies |
🔵 Blue | Dependency updates (PR label) |
invalid |
🟡 Yellow | Doesn't seem right; requires clarification |
duplicate |
⚪ Gray | Already exists (close and reference original) |
wontfix |
⚪ White | Deliberate decision not to fix |
Examples
- Bug: "fill action silently no-ops when using refs" →
bug - Enhancement: "Add CHROME_EXTENSION_PATHS support" →
enhancement - Documentation: "Update README with new CLI commands" →
documentation - Question: "How do I configure stealth mode?" →
question
Tier 2: Status (Recommended)
Choose one to show current state:
| Label | Color | Meaning | When to Use |
|---|---|---|---|
status: ready |
🔵 Blue | Ready to start work | Issue is fully understood, no blockers, waiting for someone to pick it up |
status: in-progress |
🟡 Yellow | Actively being worked on | Someone has claimed the issue and is working on a fix/feature |
status: blocked |
🔴 Red | Blocked by something | Waiting on external dependency, another issue, or decision |
status: fixed-unreleased |
🟢 Green | Fix merged, not in release | PR is merged but feature/fix isn't in a released version yet |
status: needs-investigation |
🔴 Red | Needs debugging/research | Not enough info; requires investigation before work can start |
Workflow
New Issue
↓
[Triage] Add Type + Status
↓
status: needs-investigation (if unclear) or status: ready (if clear)
↓
Developer picks it up
↓
status: in-progress
↓
PR submitted
↓
PR merged
↓
status: fixed-unreleased (for bugs) or remove status (for features)
↓
Release cut
↓
Remove status label (feature is released)
Tier 3: Priority (Optional, for bugs/enhancements)
Choose one to indicate urgency:
| Label | Color | Level | When to Use |
|---|---|---|---|
priority: high |
🔴 Red | Critical; blocks users | Security vulnerability, critical bug, high-demand feature |
priority: medium |
🟡 Yellow | Normal; important for roadmap | Important bug or feature; should be done soon |
priority: low |
🟢 Green | Nice to have; can defer | Minor improvement, polish, or edge case |
Examples
- High: "SafePath() fails to block path traversal" (security) →
bug+priority: high - Medium: "Snapshot doesn't work inside iframes" (affects users) →
bug+priority: medium - Low: "Consider migrating to PINCHTAB_* env vars" (nice refactor) →
enhancement+priority: low
Special Labels
good first issue
Add this in addition to the type label for issues that are good entry points for new contributors.
Criteria:
- Clear problem statement
- Solution is straightforward
- Doesn't require deep knowledge of codebase
- Estimated effort: <4 hours
Example: "documentation: Add /find endpoint example to README" → documentation + good first issue
help wanted
Indicates the issue needs expertise or has been stalled.
When to use:
- Needs specific expertise (e.g., "needs Windows testing")
- Issue has been open >2 weeks without progress
- Complex problem that benefits from external input
Decision Tree for Triage
New issue arrives
↓
1. Is it a valid issue?
NO → `invalid` + close
YES ↓
2. What is it?
→ Bug? `bug` + assess severity → `priority: high|medium|low`
→ New feature? `enhancement` + assess importance → `priority: high|medium|low`
→ Docs missing? `documentation` + no priority needed
→ Unclear? `question` + no priority needed
↓
3. Can we start work immediately?
YES → `status: ready`
NO ↓
4. Why not?
→ Need info → `status: needs-investigation`
→ Waiting on something → `status: blocked`
→ Already fixed → `status: fixed-unreleased`
Guidelines for Agents
When reviewing open issues, follow this checklist:
- Each issue has exactly one Type label (bug, enhancement, documentation, question)
- Bugs have Priority labels (high, medium, low)
- Enhancements have Priority labels (high, medium, low)
- Each issue has a Status label (ready, in-progress, blocked, fixed-unreleased, needs-investigation)
- No duplicate labels (e.g., two type labels on one issue)
- Status matches reality (e.g.,
status: in-progresshas an active PR) - Stale issues reviewed (e.g.,
status: blockedfor >2 weeks should note why)
Current Label Inventory
Type labels (10):
- bug, enhancement, documentation, question, good first issue, help wanted, dependencies, invalid, duplicate, wontfix
Status labels (5):
- status: ready, status: in-progress, status: blocked, status: fixed-unreleased, status: needs-investigation
Priority labels (3):
- priority: high, priority: medium, priority: low
Code labels (1):
- javascript
Examples of Well-Labeled Issues
Example 1: Security Bug
Title: SafePath() fails to block path traversal on Windows
Labels: bug, priority: high, status: ready
Why: Critical security issue, ready to work on, high priority.
Example 2: Feature Request (Ready)
Title: feat: Resource Pool with pluggable allocation strategies
Labels: enhancement, priority: medium, status: ready
Why: Enhancement, medium priority (important for roadmap), ready to start.
Example 3: Feature (Blocked)
Title: feat: Semantic Element Selection via NLP (/find endpoint)
Labels: enhancement, priority: medium, status: blocked
Why: Enhancement, medium priority, but blocked (perhaps waiting on design decision).
Example 4: Bug (Not Ready)
Title: click and humanClick fail to trigger Bootstrap dropdown
Labels: bug, priority: medium, status: needs-investigation
Why: Bug, medium priority, but needs investigation (reproduction steps unclear).
Example 5: Already Fixed
Title: Installation issue
Labels: bug, priority: high, status: fixed-unreleased
Why: Critical bug, but fix is already merged and waiting for release.
Common Mistakes
❌ Don't do this:
| Mistake | Why | Fix |
|---|---|---|
| Two Type labels on one issue | Ambiguous; what is it really? | Choose one type only |
| Status label on closed issue | Status should reflect open work | Remove status label when closing |
| No Priority on bugs | Can't triage effectively | Add priority: high/medium/low to all bugs |
status: in-progress with no PR |
Misleading; is someone actually working on it? | Only use when work is actively underway |
| Forgetting Status labels | No visibility into progress | Always add a status label during triage |
Related Documents
- DEFINITION_OF_DONE.md — Checklist for PRs before merge
- CONTRIBUTING.md — Contribution guidelines (if present)
Last Updated
2026-03-04
Summary
For agents: Use this guide to understand and apply labels when triaging issues. Ensure every issue has Type + Status + Priority (if applicable).
For maintainers: Review labels during triage and ensure consistency. Use the Decision Tree above as a quick reference.