codyswanngt/linear-journey

Linear Validation Journey

Parse a Linear Issue's Validation Journey, execute the verification steps using the appropriate tools for the change type, capture evidence at each [EVIDENCE: name] marker, and post to Linear + GitHub PR.

This skill is the destination of the lisa:tracker-journey shim when tracker = "linear".

Configuration

Reads linear.workspace, linear.teamKey from .lisa.config.json (with .local override).

Arguments

$ARGUMENTS: <IDENTIFIER> [PR_NUMBER]

• IDENTIFIER (required): Linear Issue identifier (e.g. ENG-123)
• PR_NUMBER (optional): GitHub PR number to update description

Prerequisites

• Linear MCP authenticated
• gh CLI authenticated
• Appropriate services running for the verification type (dev server, database, etc.)

Workflow

Step 1: Parse the Validation Journey

Fetch the Issue via mcp__linear-server__get_issue and extract the ## Validation Journey section from the markdown description. Parse:

• ### Prerequisites — list of required services / env / setup
• ### Steps — numbered steps, each potentially containing [EVIDENCE: name] markers
• ### Assertions — what must be true after verification

If the section is missing or has no steps, report "No Validation Journey on <IDENTIFIER>. Run /linear-add-journey first." and stop.

Step 2: Satisfy Prerequisites

Before executing steps, verify each prerequisite:

1. Required services running (dev server, database, queue worker)
2. Database connectivity if needed
3. Environment variables set
4. Run any setup commands mentioned in prerequisites

Stop and report if any prerequisite is not satisfied.

Step 3: Execute Steps and Capture Evidence

Execute each step sequentially. Determine the verification approach based on the step text and change type:

• API endpoints → Run curl commands, capture HTTP response to evidence/NN-name.txt (or .json for structured data)
• Database changes → Run psql / migration commands, capture schema output
• Background jobs → Trigger the job, check queue / state, capture logs
• Library / utility changes → Run tests, capture output
• Security fixes → Reproduce exploit attempt, verify fix
• UI / frontend → Playwright browser flow, capture screenshots / DOM state

At each [EVIDENCE: name] marker, capture stdout / stderr to a numbered file:

Evidence Naming Convention

{NN}-{evidence-name}.{ext}

• NN: zero-padded sequential number (01, 02, 03...)
• evidence-name: the value from [EVIDENCE: name]
• ext: .txt for plain output, .json for structured data

Example:

evidence/
  01-health-check.json
  02-schema-after-migration.txt
  03-rate-limit-response.txt
  comment.txt
  code-blocks.md

Step 4: Generate Evidence Comment + Code Blocks

After capturing all evidence, build:

• evidence/comment.txt — human-readable summary of the verification (Linear comment body, markdown-supported)
• evidence/code-blocks.md — fenced code blocks containing the captured evidence outputs (appended below comment.txt inside a <details> block)

Step 5: Post Evidence

Invoke lisa:linear-evidence with <IDENTIFIER> ./evidence to:

1. Upload large evidence files to the GitHub pr-assets release (if files present in evidence/files/).
2. Update the GitHub PR description with an Evidence section (when a PR is open).
3. Post the Linear comment (comment.txt + collapsible code-blocks.md).
4. Transition labels: remove status:in-progress, add status:code-review.

Step 6: Verify

Confirm:

• Evidence appears as a comment on the Linear Issue.
• The PR description shows the Evidence section.
• The Issue's status:* label transitioned to code-review.

Verification Patterns Reference

Use patterns from the project's verification.md:

| Change Type | Verification Method | Evidence Format | |---|---|---| | API endpoint | curl -s localhost:PORT/endpoint | JSON response | | Database migration | psql -c "\d table" or migration output | Schema text | | Background job | Trigger + check state | Log output | | Library / utility | bun run test -- path/to/test | Test output | | Security fix | Reproduce + verify fix | Request / response | | Auth/authz | Multi-role verification | Status codes per role | | UI / frontend | Playwright browser_* MCP tools | Screenshot + DOM |

Troubleshooting

Evidence file is empty

Ensure the command succeeded and produced output. Use 2>&1 to capture both stdout and stderr.

Parser returns no steps

The Issue may not have a Validation Journey section. Run /linear-add-journey <IDENTIFIER> to add one.

Label transition fails

Ensure status:in-progress and status:code-review exist on the team. lisa:linear-evidence creates them on demand if missing.