linear-journey

name	linear-journey
description	Parse a Linear Issue's Validation Journey section, execute the verification steps using appropriate tools (curl, test commands, database queries, Playwright), capture evidence at each [EVIDENCE: name] marker, and post to Linear + GitHub PR using the linear-evidence skill. Linear counterpart of lisa:jira-journey.
allowed-tools	["Bash","Read","Glob","Grep","Skill"]

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 lisa:linear-access operation: 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.