update-linear-post-job

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
created	"2025-11-05T00:00:00.000Z"
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:

1. Phase 1: Research (no branch yet)
2. Phase 2: Spec clarification (no branch yet)
3. Phase 3: Linear Enrichment (no branch yet)
4. Just before Phase 4: Create branch
5. Phase 4-6: QA creates tests → Action implements → QA validates (on branch)
6. 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
• Related Ref-Docs:
  • tdd-workflow-protocol.md - Full 7-phase TDD workflow
  • master-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