symphony-workpad

Workpad

The workpad is the single source of truth for an issue's plan, acceptance criteria, validation, and notes. One ## Symphony Workpad comment per issue, ever — never open a second one, never delete it.

Find or bootstrap

1. List comments on the issue with the configured Linear MCP comment-listing tool, normally mcp__linear__list_comments in Codex.
2. Find the comment whose body starts with ## Symphony Workpad. If found: persist its id for in-place updates and reuse it.
3. If not found, create one with the configured Linear MCP comment-save tool, normally mcp__linear__save_comment in Codex, using the template at the bottom of this skill. Persist the returned id.

Update in place (the trap)

The Linear MCP save_comment tool with a commentId creates a new comment instead of editing the original — this is what produces duplicate workpads. Always update via raw GraphQL:

curl -fsS \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.linear.app/graphql \
  -d @- <<'JSON'
{"query":"mutation($id:String!,$body:String!){commentUpdate(id:$id,input:{body:$body}){success}}",
 "variables":{"id":"<comment-id>","body":"<new body>"}}
JSON

If duplicates were already created by a buggy save, edit the canonical (oldest) workpad in place via the GraphQL workaround and replace the duplicate's body with Superseded — see canonical Symphony Workpad above.. Do not delete the duplicate — the workpad comment, even a duplicate one, is never test data.

Reset (Rework)

When the issue moves to Rework, overwrite the existing workpad's body in place with a fresh scaffold via the same commentUpdate mutation. Do not delete the comment. Keep the same comment ID for the lifetime of the issue.

Acceptance criteria & validation

• Capture every checkbox the workflow requires (env stamp, plan, acceptance, validation, notes).
• If the issue body has Validation, Test Plan, or Testing sections, copy them verbatim into Acceptance / Validation as required checkboxes — no optional downgrade.
• For user-facing changes, add a UI walkthrough criterion. Screenshots themselves go in the PR description via the symphony-screenshot skill, not in the workpad.