Issue Writer

This skill expands brief Linear issue summaries into comprehensive "task packets" that autonomous AI agents can execute successfully. Claude does the expansion natively using its full codebase context — no subprocess spawning.

When to Use

Use this skill when:

• Preparing issues for autonomous agent execution (via hokusai-orchestrator)
• Issues have minimal description but need detailed implementation guidance
• Creating task specifications for parallel workflow execution
• Converting feature requests into actionable technical specs

Instructions

Step 1: Fetch the Issue

npx tsx ~/.claude/tools/get-issue.ts HOK-XXX

Review the output: title, current description, project, state, priority, labels, parent/child relationships, and comments.

Step 2: Explore the Codebase

Use Explore agents (Task tool with subagent_type: "Explore") to find:

• Files that will need to be created or modified
• Existing patterns and conventions to follow
• Related implementations to use as reference
• Dependencies and integration points

Run multiple Explore agents in parallel for different aspects (e.g., one for UI patterns, one for service layer, one for tests).

Step 3: Generate the Task Packet

Write the expanded description following the structure in ~/.claude/tools/prompts/issue-writer.md:

1. Objective — What / Why / Scope In / Scope Out
2. Technical Context — Repository, key files, dependencies, architecture notes
3. Implementation Approach — Step-by-step plan with concrete actions
4. Success Criteria — Functional, non-functional, code quality (specific and measurable)
5. Implementation Constraints — Code style, testing, security, performance rules
6. Validation Steps — Exact commands to run with expected output
7. Definition of Done — Final checklist
8. Rollback Plan — How to undo safely

Key principles:

• Specificity over brevity — over-specify rather than under-specify
• Include exact file paths — not just "the component file"
• Measurable criteria — "loads in <2s" not "should be fast"
• Validation-first — agent should know how to verify success before starting
• Reference existing code — point to similar implementations as patterns to follow

Step 3.5: Auto-Generate Labels

After generating the task packet, analyze the content and prepare labels for the issue:

1. Extract Files to Modify

   • Parse file paths from the Technical Context and Implementation Approach sections
   • Add as metadata: Files: <path1>, <path2>, ... (limit to first 3 files)

2. Assess Risk Level

   • Check for: breaking changes, migrations, schema changes, infrastructure changes
   • Risk: High — Breaking changes, migrations, infrastructure, major refactors
   • Risk: Medium — New features, non-trivial refactoring, API changes (default)
   • Risk: Low — CSS/styling, text updates, documentation, typo fixes

3. Identify Architectural Layer

   • Parse file paths and implementation approach
   • Layer: UI — Components, frontend code (.tsx, .jsx, components/)
   • Layer: API — API routes, endpoints (/api/, routes/)
   • Layer: Service — Business logic, services (services/, lib/)
   • Layer: Database — Schema, migrations, queries (schema.prisma, migrations/)
   • Layer: Infra — Config, deployment, CI/CD (Dockerfile, .github/, deploy/)

4. Identify Area (product areas only — use Layer labels for architectural layers)

   • Based on feature/component affected:
   • Area: Landing — Landing page, homepage, hero
   • Area: Navigation — Nav, menus, routing
   • Area: Auth — Authentication, authorization, login
   • Area: Docs — Documentation, README

5. Check Test Requirements

   • Parse Validation Steps section
   • Tests: E2E — End-to-end tests (Playwright, Cypress)
   • Tests: Integration — Integration tests
   • Tests: Unit — Unit tests (Jest, Vitest)
   • Tests: None — No tests required

6. Extract Dependencies (if mentioned)

   • Look for references to other issues (HOK-XXX)
   • Add: Blocked-By: HOK-XXX or Related-To: HOK-XXX

Add these labels as a section at the bottom of your task packet:

---
## Proposed Labels
- Risk: Medium
- Layer: UI
- Area: Landing
- Tests: Unit
- Files: src/components/Hero.tsx, src/hooks/useTheme.ts

Step 4: Write to Temp File and Update Linear

Save the expanded description to a temp file, then push it to Linear:

# Write expanded description to temp file (use Write tool)
# Then update Linear:
npx tsx ~/.claude/tools/update-issue.ts HOK-XXX --file /tmp/hok-xxx-expanded.md

Step 5: Apply Auto-Labels

After updating the issue description, automatically apply the proposed labels:

npx tsx ~/.claude/tools/auto-label-issue.ts HOK-XXX

This will:

• Parse the issue description and title
• Detect risk level, layers, areas, files, and test requirements
• Apply matching labels to the issue in Linear
• Report which labels were applied

If labels don't exist yet, create them first:

npx tsx ~/.claude/tools/init-labels.ts

Step 6: Report Back

Tell the user:

• The Linear issue URL
• A brief summary of what was expanded
• Which labels were applied
• Any concerns or ambiguities found during exploration

Task Packet Quality Checklist

Before updating Linear, verify the expanded issue includes:

• Specific, measurable success criteria (not vague)
• Exact file paths that will be modified
• Concrete validation commands with expected output
• Clear scope boundaries (what's NOT included)
• Security/performance constraints if applicable
• Rollback instructions
• References to existing patterns/implementations

Examples by Task Type

Feature Addition

Focus on: User stories, UI/UX requirements, integration points, existing component patterns Example: "User can upload avatar (JPEG/PNG, max 5MB, 1:1 crop, S3 storage)"

Bug Fix

Focus on: Root cause, reproduction steps, regression prevention Example: "Fix race condition in WebSocket reconnect (add mutex, test with 1000 concurrent connections)"

Refactoring

Focus on: What's changing structurally, what's NOT changing behaviorally Example: "Extract auth logic into reusable hooks (identical test output before/after)"

Performance Optimization

Focus on: Measurable metrics (bundle size, render time, API latency) Example: "Reduce dashboard load time from 2.3s to <1s (lazy load charts, virtualize lists)"

Environment Setup

Requires:

• LINEAR_API_KEY in .env

Batch Usage

To expand multiple issues, invoke the skill repeatedly:

/issue-writer HOK-101
/issue-writer HOK-102
/issue-writer HOK-103

After expanding, use with hokusai-orchestrator for parallel execution.