issue-tracking-with-beans-and-linear
Use when starting work, tracking tasks, or deciding where to record discovered work - clarifies when to use Beans vs Linear
When & Why to Use This Skill
This Claude skill establishes a sophisticated task-tracking hierarchy that bridges the gap between agent-specific implementation memory (Beans) and human-centric project management (Linear). It optimizes the developer workflow by providing clear rules for task persistence, discovered work escalation, and bidirectional traceability, ensuring that technical implementation details are preserved without cluttering high-level project boards.
Use Cases
- Workflow Initialization: Automatically creating a Beans epic when starting a Linear ticket to track granular implementation steps and maintain an audit trail.
- Discovered Work Management: Categorizing unexpected tasks found during development as either 'implementation details' for Beans or 'scope changes' for Linear escalation.
- Git Traceability: Standardizing commit messages to include references to both Linear tickets and Beans issues for permanent historical context.
- Context Retrieval: Using Beans to trace the technical origin and 'why' behind vague Linear tickets, providing agents with deeper implementation provenance.
- Session Continuity: Leveraging Beans as a persistent memory layer to resume complex, multi-step tasks across different AI agent sessions.
| name | issue-tracking-with-beans-and-linear |
|---|---|
| description | Use when starting work, tracking tasks, or deciding where to record discovered work - clarifies when to use Beans vs Linear |
Task Tracking Hierarchy
Two systems serve different purposes. Use the right tool for the job.
| System | Purpose | Persistence | Audience |
|---|---|---|---|
| Beans | Agent memory & audit trail | Git-tracked | Agents, future sessions |
| Linear | Project tracking | External | Humans |
Linear is for human-visible project tracking. Beans is for agent implementation memory. Both systems work together with bidirectional linking.
When to Use Each System
Beans — Persistent agent memory (only if the project uses Beans):
- All non-trivial work (3+ steps)
- Work that may span sessions or context boundaries
- Discovered work during implementation
- Anything needing an audit trail
- Skip for trivial single-step tasks (typo fixes, quick lookups)
Linear — Human-level tracking:
- Epics and milestones
- User-facing features
- Scope/timeline changes
- Decisions requiring human input
- Security concerns
Starting Work on a Linear Ticket
When beginning work on a Linear ticket (e.g., ZCO-123):
- Run
beans query '{ beans(filter: { type: ["epic"], search: "\"<linear-ticket-id>\"" }) { id title status } }'to find an existing related Beans epic - If none exists, create one automatically:
beans create "<linear-ticket-id>: <design-name>" --type epic --body "<description>" - All implementation sub-tasks go under this epic as child issues using
--parent <epic-id>
Git Commit Messages
All commits related to a Linear ticket MUST reference it:
<descriptive message>
Part of ZCO-123.
When also closing a Beans issue:
<message>
Part of ZCO-123. Closes beans-1234.
This ensures Linear ticket traceability in git history even after Beans cleanup.
Rule: Discovered Work Goes to Beans First
When you discover work during implementation:
- Create a bean immediately (
--tag discovered), add a line that explains that it was created while working on current bean, and name the current bean. - Assess if it needs Linear escalation
- Never ignore discovered work due to context pressure
Rule: Escalate Discovered Work to Linear
Create a Linear ticket for discovered work IF it:
- Affects scope or timeline of current work
- Requires human decision or approval
- Represents user-facing changes
- Is a security concern
- Is significant enough to track at project level
For purely technical implementation details (refactoring, test fixes, code cleanup), keep them in Beans only with --tag implementation-detail.
When Beans work reveals an epic-level concern:
- Create the bean with
--type epic - Immediately create a corresponding Linear ticket, tag it as "Epic"
- Cross-reference both directions
Querying Work
beans list --status backlog— Find unblocked work to do nextbeans list --search "<linear-ticket-id>"— All Beans issues for a Linear ticketbeans show <id>— View issue details including dependencies
Provenance for Context
When revisiting a Linear ticket that seems vague, use Beans to trace its origin:
- Find the Beans epic:
beans list --type epic | rg --fixed-strings '<linear-ticket-id>' - Use
--tag discovered --link:<epic-ticket-id>to understand why work was filed - This provides context that Linear alone cannot
Completing a Linear Ticket
When all Beans issues under an epic are closed:
- Update the Linear ticket with a summary:
- What was implemented
- Any discovered work filed as separate Linear tickets
- Notable decisions or deviations from original scope
- Move the Linear ticket to appropriate status
The Linear ticket becomes the permanent record; Beans issues are ephemeral working memory.