Ticket Scoping

Every piece of work flows through Linear. These conventions ensure tickets are consistently scoped, estimated, and traceable. The goal is predictable delivery and honest velocity data -- not bureaucracy.

Ticket Structure

Every feature ticket has two clearly separated sections:

1. Core Scope

The feature functionality itself -- what the system does for end users or other systems.

2. Admin Logging and Debugging Tools

Every ticket that builds backend systems, stores data, processes user input, integrates with external services, or performs operations that could fail silently must include an admin logging and debugging UI section.

Why this is non-negotiable: The founder is building this app with AI agents. Without admin tools to verify each feature works correctly, silent failures compound and trust in the system erodes. The AI Logs page (TRO-22) is the template -- every feature should have equivalent visibility.

What needs admin logging scope

Tickets involving any of these require it:

• External API calls (Claude, Gemini, any third-party service)
• Data persistence (storing user data, artifacts, memories, preferences)
• Background processing (jobs, webhooks, scheduled tasks)
• MCP operations (tool invocations, resource reads/writes)
• Auth/security flows (OAuth, token management)
• File processing (uploads, conversions, generation)
• AI-powered features (any use of @repo/ai)
• Multi-system orchestration (reading from memory + artifacts + calling AI)

What does not need admin logging scope

• Static pages (landing page, privacy policy, terms of service)
• Simple CRUD UI where failures are immediately visible to the user
• Frontend-only UX features (tooltips, guided tours, onboarding flows that do not process data)
• Configuration/audit tasks using external dashboards (Statsig flags, Sentry setup)
• Read-only aggregation views (dashboards that display existing data)

The admin logging UI pattern

Follow the pattern established in TRO-22 (AI Logs):

1. Log Table -- filterable, paginated list of operations with key metadata columns
2. Detail View -- click a row to see everything stored about that operation (collapsible sections)
3. Dashboard/KPIs -- summary stats (total operations, failure rates, performance metrics)
4. Debugger/Playground (where applicable) -- interactive tool to test the feature's behavior manually

All admin pages go under /admin/ routes and the Admin sidebar section.

Story Point Estimation

All tickets must have an estimate before work begins. Unestimated tickets should not move to "In Progress."

Point scale

Points	Meaning
1	Trivial -- a single well-understood change, minimal testing (less than half a session)
2	Small -- a few files, straightforward logic, clear path (roughly one focused session)
3	Medium -- multiple files or one new subsystem, some decisions to make (one full work session)
5	Large -- multiple subsystems, new patterns, or significant integration work (2-3 sessions)
8	XL -- cross-cutting changes, new infrastructure, or significant unknowns (full week)

Use Fibonacci values only (1, 2, 3, 5, 8). If an estimate exceeds 8 points, the ticket is too large -- break it into smaller tickets before starting work.

Accounting for admin logging scope

When estimating, explicitly add points for the admin logging and debugging UI:

Core complexity	Logging scope	Typical total
Simple CRUD (1-2 pts)	Basic log table + detail view (+1 pt)	2-3 pts
Backend system (2-3 pts)	Log table + detail + dashboard (+2 pts)	4-5 pts
External API integration (3 pts)	Full logging + playground/debugger (+2-3 pts)	5-6 pts
Multi-system orchestration (3-5 pts)	Full logging + debugger + cross-system visibility (+2-3 pts)	5-8 pts

A ticket estimated without logging scope should be flagged and re-estimated before work begins.

Keeping estimates honest

• Re-estimate when scope changes. If a ticket's scope grows during work, update the estimate to reflect reality. This keeps historical data useful for future planning.
• Compare against past tickets. Before estimating, glance at completed tickets of similar complexity.
• Estimate the work, not the worker. Points measure the size of the task, not how fast you will go.

Feature Scope Rule

Feature issues cover one week's scope only. New issues are created weekly for ongoing work. This prevents tickets from becoming stale catch-all containers and keeps the backlog honest about what is actually planned.

Issue Relations

Use Linear's relation system to maintain traceability:

• "Related to" -- when a ticket is created as a direct consequence of work done in another ticket. Set this when creating the downstream ticket, not retroactively.
• "Blocked by" / "Blocks" -- when a ticket literally cannot start until another is complete.
• "Duplicate of" -- when two tickets describe the same work.

When to set relations:

• Always link downstream tickets back to the ticket that caused them
• Always link tickets that share the same milestone and were created in the same session
• Set relations at ticket creation time -- do not rely on remembering to add them later

Other Guidelines

• Branch names come from Linear (e.g., kyleolson512/tro-22-ai-api-layer-claude-api-integration)
• Description should include "Depends on" references to upstream tickets
• Labels: use foundation for infrastructure/platform work, Feature for user-facing features, and week-N for scheduling
• Update ticket descriptions after completion to reflect actual delivered scope

Related Pages

• Handbook -- Conventions -- Commit Workflow -- the commit process that follows ticket work
• Handbook -- Conventions -- Technical Debt -- how TODO comments reference ticket IDs