update-linear-post-job
Three-step Linear update protocol after job completion - update child issue, check parent completion, update parent if all children done
When & Why to Use This Skill
This Claude skill automates the Linear issue lifecycle through a rigorous three-step update protocol. It ensures project data integrity by automatically transitioning child issues to 'Done', verifying the completion status of sibling tasks, and conditionally updating parent work blocks. By standardizing comments and handoff reports, it eliminates manual tracking overhead and maintains a clear audit trail for development teams using Linear.
Use Cases
- Automating the transition of Linear child issues to 'Done' immediately after PR merges and QA approval to maintain real-time project status.
- Synchronizing parent task statuses by automatically checking if all sub-tasks are completed before closing a major work block.
- Generating standardized completion comments in Linear that include PR links, QA status, and file change summaries for better team visibility.
- Streamlining the 'Tracking Agent' phase in a TDD workflow to ensure seamless handoffs between Planning and Action agents.
| name | Update Linear Post-Job |
|---|---|
| description | Three-step Linear update protocol after job completion - update child issue, check parent completion, update parent if all children done |
| category | workflow |
| usage | tracking |
| version | 1.0 |
| created | 2025-11-05 |
| converted_from | docs/agents/shared-ref-docs/post-job-linear-updates.md |
Update Linear Post-Job
When to Use
Use this skill when:
- Job completion (Tracking Agent): After QA validates implementation and Planning Agent confirms job complete
- Phase 7 of TDD workflow: Tracking Agent handles PR/documentation and Linear updates
- Work block tracking: Need to update child issue status and check parent completion
Triggers:
- Planning Agent confirms job completion
- QA Agent approves implementation
- PR is merged and job is ready for closure
- Need to track work block progress in Linear
TDD Workflow Context:
- 7-Phase TDD: Research → Spec → Linear Enrichment → QA (tests) → Action (code) → QA (validate) → Tracking (PR/docs) → Dashboard Update
- This skill: Executes during Phase 7 (Tracking Agent responsibilities)
Workflow
Step 1: Update Child Issue Status
Purpose: Mark the completed job (child issue) as Done in Linear
Prerequisites:
- Planning Agent confirmed job completion
- QA Agent approved implementation
- PR merged (if applicable)
- Handoff includes child issue ID
Execute:
// Update child issue to Done
await mcp__linear-server__update_issue({
id: "LAW-5", // Child issue ID from handoff
state: "Done"
})
Then add completion comment:
await mcp__linear-server__create_comment({
issueId: "LAW-5",
body: `✅ **Job Complete**
**PR**: #14 (https://github.com/org/repo/pull/14)
**QA Status**: ✅ All tests passing
**Files Changed**: 8 files, +420/-15 lines
Ready for merge.`
})
Comment Template Fields:
- PR: Link to merged pull request (if applicable)
- QA Status: Confirmation that QA validation passed
- Files Changed: Summary of code changes
- Additional Notes: Any relevant completion details
Error Handling:
If update fails, add comment instead and continue:
try {
await mcp__linear-server__update_issue({ id: "LAW-5", state: "Done" })
} catch (error) {
await mcp__linear-server__create_comment({
issueId: "LAW-5",
body: `⚠️ **Tracking Agent**: Could not update issue status to Done.
Error: ${error.message}
Job completion confirmed by Planning Agent. Manual status update needed.`
})
// Continue to Step 2 - don't block on child update failure
}
Step 2: Check Parent Work Block Completion
Purpose: Determine if all child jobs in the work block are complete
Execute:
// 1. Get parent issue details
const parentIssue = await mcp__linear-server__get_issue({
id: "LAW-4" // Parent work block ID from handoff
})
// 2. Get all child issues of parent
const childIssues = await mcp__linear-server__list_issues({
team: "Linear-First-Agentic-Workflow", // From .project-context.md
parentId: "LAW-4" // Parent work block ID
})
// 3. Check if ALL children are Done
const allChildrenDone = childIssues.nodes.every(
issue => issue.state.name === "Done"
)
Decision Point:
- If
allChildrenDone === true: Proceed to Step 3 (update parent) - If
allChildrenDone === false: Skip to Step 4 (report to Planning Agent)
What to check:
- All child issues must have
state.name === "Done" - Check all siblings (other child issues under same parent)
- Do not update parent if any child is still In Progress, Todo, or Blocked
Step 3: Update Parent Work Block (If All Children Complete)
Purpose: Mark parent work block as Done when all child jobs complete
Execute only if Step 2 determined all children are Done:
// Update parent work block to Done
await mcp__linear-server__update_issue({
id: "LAW-4",
state: "Done"
})
// Add completion comment to parent
await mcp__linear-server__create_comment({
issueId: "LAW-4",
body: `✅ **Work Block Complete**
All child jobs completed:
- LAW-5: Research Agent Upgrade ✅
- LAW-6: Planning Agent Refactor ✅
- LAW-7: Tracking Agent Updates ✅
[... list all completed children ...]
All PRs merged. Work block ready for closure.`
})
Comment Template for Parent:
- List all completed child jobs
- Confirm all PRs merged
- Note that work block is ready for closure
Error Handling:
If parent update fails, report to Planning Agent but don't block:
try {
await mcp__linear-server__update_issue({ id: "LAW-4", state: "Done" })
} catch (error) {
// Report error to Planning Agent
// Continue - job is still complete even if parent update fails
}
Step 4: Report to Planning Agent
Purpose: Notify Planning Agent of completion and any issues
Write completion report to handoff location (specified by Planning Agent):
If all updates successful:
**Tracking Agent Completion Report**
✅ **All Linear Updates Complete**
**Child Issue**: LAW-5 updated to Done
**Parent Work Block**: LAW-4 [updated to Done | still has N incomplete children]
**Summary**:
- PR #14 merged successfully
- Linear issues updated
- Work block [complete | in progress]
[If parent complete] Master Dashboard update delegated to Traycer per Phase 7 protocol.
Ready for next job.
If errors occurred:
**Tracking Agent Completion Report**
⚠️ **Linear Updates Completed With Errors**
**Child Issue**: LAW-5 - [updated successfully | update failed, manual intervention needed]
**Parent Work Block**: LAW-4 - [checked, N of M children complete | check failed]
**Errors**:
- [List any errors encountered]
**Action Required**:
- [List manual steps needed to resolve errors]
Job completion confirmed despite Linear update errors.
Important: Do NOT update Master Dashboard - this is delegated by Traycer per Phase 7 protocol
Reference
Complete Example Flow
Scenario: LAW-5 (Research Agent Upgrade) complete, parent is LAW-4
// Step 1: Update child issue
await mcp__linear-server__update_issue({
id: "LAW-5",
state: "Done"
})
await mcp__linear-server__create_comment({
issueId: "LAW-5",
body: "✅ Job complete. PR #14 merged."
})
// Step 2: Check parent completion
const parentIssue = await mcp__linear-server__get_issue({ id: "LAW-4" })
const childIssues = await mcp__linear-server__list_issues({
team: "Linear-First-Agentic-Workflow",
parentId: "LAW-4"
})
const allDone = childIssues.nodes.every(i => i.state.name === "Done")
// Step 3: Update parent if all children complete
if (allDone) {
// All 9 child jobs complete
await mcp__linear-server__update_issue({
id: "LAW-4",
state: "Done"
})
await mcp__linear-server__create_comment({
issueId: "LAW-4",
body: "✅ All 9 child jobs complete. Work block done."
})
}
// Step 4: Report to Planning Agent
// Write completion report to handoff location
// Do NOT update Master Dashboard (delegated by Traycer)
Branch Creation Context
Note: This skill executes AFTER branch creation and PR merge
7-Phase TDD Workflow:
- Phase 1: Research (no branch yet)
- Phase 2: Spec clarification (no branch yet)
- Phase 3: Linear Enrichment (no branch yet)
- Just before Phase 4: Create branch
- Phase 4-6: QA creates tests → Action implements → QA validates (on branch)
- Phase 7: Tracking Agent handles PR/docs and Linear updates ← This skill
Branch Naming Convention (for reference):
Pattern: feat/<parent-issue-id>-<child-issue-id>-<slug>
Examples:
# Work Block: LAW-4, Child Job: LAW-5
feat/law-4-law-5-research-agent-upgrade
# Work Block: LAW-350, Child Job: LAW-351
feat/law-350-law-351-webhook-server-setup
Related Tools
- Linear MCP:
mcp__linear-server__update_issue,mcp__linear-server__get_issue,mcp__linear-server__list_issues,mcp__linear-server__create_comment - Project Context:
.project-context.md(contains team name for Linear queries) - Handoff Files: Planning Agent provides child/parent issue IDs
Related Documentation
- Original Reference: post-job-linear-updates.md (deprecated - use this skill instead)
- Agent Prompts:
- Tracking Agent:
docs/agents/tracking/tracking-agent.md - Planning Agent:
docs/agents/planning/planning-agent.md
- Tracking Agent:
- Related Ref-Docs:
tdd-workflow-protocol.md- Full 7-phase TDD workflowmaster-dashboard-creation-protocol.md- Dashboard update protocol (delegated by Traycer)linear-update-protocol.md- General Linear API usage
Decision Matrix
| Condition | Action |
|---|---|
| Child update succeeds | Proceed to parent check |
| Child update fails | Add error comment, continue to parent check |
| All children Done | Update parent to Done, add completion comment |
| Some children incomplete | Skip parent update, report status to Planning Agent |
| Parent update fails | Report error, continue (don't block on parent failure) |
| All updates complete | Report success to Planning Agent |
Common Pitfalls to Avoid
❌ Don't: Update Master Dashboard directly
- Why: Dashboard updates are delegated by Traycer per Phase 7 protocol
- Instead: Report completion to Planning Agent, let Traycer coordinate dashboard update
❌ Don't: Block if parent update fails
- Why: Child job is complete regardless of parent status
- Instead: Report error to Planning Agent, mark job as complete
❌ Don't: Assume all children Done without querying
- Why: Another agent might have deferred a child job
- Instead: Always query all child issues and check state
❌ Don't: Update child issue state to "Closed" or "Canceled"
- Why: "Done" is the correct state for completed jobs
- Instead: Always use "Done" state
Version History
- v1.0 (2025-11-05): Converted from post-job-linear-updates.md to skill format
- Extracted 3-step workflow from reference doc
- Added error handling examples
- Clarified decision points and delegation boundaries
- Included complete example flow