codyswanngt Add Validation Journey to Existing Linear Issue
Read an existing Linear Issue, analyze the change type, and append a Validation Journey section to the description with appropriate verification steps based on the project's verification patterns.
This skill is the destination of the lisa-tracker-add-journey shim when tracker = "linear".
Configuration
Reads linear.workspace, linear.teamKey from .lisa.config.json (with .local override).
Arguments
$ARGUMENTS: <IDENTIFIER> — Linear Issue identifier (e.g. ENG-123).
Workflow
Step 1: Read the Issue
Fetch via lisa-linear-access operation: get-issue and extract: title, description (markdown), labels, project, parent, attachments.
Step 2: Check for Existing Journey
If the description contains a ## Validation Journey section, inspect that section for at least one local typed [EVIDENCE: <artifact-type>: <name>] marker. Stop only when that local marker exists. An [EVIDENCE-REF: <work-item-ref> | <artifact-type>: <kebab-case-name>] is a non-claiming pointer and does not count; if the journey has references but no local claiming marker, continue drafting the missing local journey evidence. Preserve the existing journey prose and references when appending the local evidence rather than overwriting them.
Step 3: Analyze the Change Type
Examine the description, acceptance criteria, and codebase to determine the change type:
- API/GraphQL — New or modified endpoints, request/response schemas
- Database migration — Schema changes, new tables/columns, indexes
- Background job/queue — New job processors, queue consumers, event handlers
- Library/utility — Exported functions, shared modules, npm package changes
- Security fix — Auth, authorization, input validation, OWASP vulnerabilities
- Authentication/authorization — Role-based access, session management, tokens
- UI/frontend — Components, flows, browser-driven verification
Use Explore agents or read the codebase to understand which files are affected and what verification approach is appropriate.
Step 4: Map Change Type to Verification Pattern
| Change Type | Verification Approach |
|---|---|
| API/GraphQL | curl commands verifying endpoints, status codes, response schemas |
| Database migration | Migration execution + schema verification + rollback check |
| Background job/queue | Enqueue + process + state change verification |
| Library/utility | Test execution + build verification + export check |
| Security fix | Exploit reproduction pre-fix + exploit failure post-fix |
| Auth/authz | Multi-role verification with explicit status codes |
| UI/frontend | Playwright browser flow + visual evidence |
Step 5: Draft the Validation Journey (markdown)
Linear descriptions are markdown. Use ## and ### headings — not Jira wiki markup.
Compose the journey with typed [EVIDENCE: <artifact-type>: <name>] markers at key verification points. The type says HOW the proof is captured (screenshot, recording, http-transcript, cli-output, log-snippet, db-query-output, perf-trace, test-run-log, deploy-log, state-dump — the fixed taxonomy in the verification rule); the name says WHAT it proves.
## Validation Journey
### Prerequisites
- List required services, database, env vars
### Steps
1. Verify current state before changes
2. Apply the change
3. Verify expected new state [EVIDENCE: http-transcript: health-endpoint-200]
4. Test error/edge cases [EVIDENCE: screenshot: invalid-input-error-state]
5. Verify rollback if applicable [EVIDENCE: db-query-output: rows-restored-after-rollback]
### Assertions
- Describe what must be true after verification
Guidelines for Drafting
- 2–5 evidence markers — Focus on proving the change works and handles errors.
- Concrete, runnable steps —
Run \curl -s localhost:3000/health | jq .status`` not "Check the endpoint". - Include environment setup — Database connection, running services, env vars.
- Markers are typed artifacts, not assertion labels —
[EVIDENCE: <artifact-type>: <kebab-case-name>].[EVIDENCE: load-failure-handled-gracefully]names a claim with nothing to capture; write[EVIDENCE: screenshot: load-failure-error-state]or[EVIDENCE: perf-trace: pipeline-load-tti]. Names are kebab-case and unique within the ticket. - Assertions are measurable — "Returns 200 with
{status: ok}" not "API works correctly". - Cover happy path and error path — At minimum, one success and one failure evidence marker.
- On a leaf work unit, the markers are binding — For a Bug / Task / Sub-task / Improvement, every typed
[EVIDENCE: <artifact-type>: <name>]here is the item's evidence manifest: validation gate S14 requires at least one, and the item cannot be closed until each named artifact is captured in its declared type and attached (see the "Per-Work-Unit Evidence Contract" in theverificationrule). Name only evidence you intend to capture — and name all of it. - Reference sibling evidence without claiming it — Use only
[EVIDENCE-REF: <work-item-ref> | <artifact-type>: <kebab-case-name>]when prose points to an artifact declared by another item. Never paste, quote, or code-format the sibling's[EVIDENCE: ...]marker: that exact prefix creates a local obligation.EVIDENCE-REFnever satisfies this item's S14 minimum, uniqueness check, capture list, or completion gate; a runtime-changing leaf still needs at least one local[EVIDENCE: ...]marker. - A named existing test is a control, and a control declares its reachability — When the journey pins an existing test as a red-before-green control ("must go red", "fails before the fix and passes after"), the
control-reachabilityrule requires the item to say what makes that test reach the changed code:[CONTROL: <test-identifier> | reaches: <input-or-field>], one per named control, validated by gate S20. Name the fixture key, field, argument, or state that carries execution into the change — not the code itself. A test whose fixture never reaches the changed path stays green for a reason unrelated to the change, and the stopping rule then reads as "revert a correct fix". Introducing a new test instead carries no such obligation; S20 isN/Aand no marker is written.
Step 6: Present to User for Approval
Display the drafted journey change and ask for confirmation before updating the issue.
Step 7: Merge into Issue Description
After approval, fetch the current description and update via lisa-linear-access operation: save-issue({id, description: <new-description>}). If no journey exists, append one section. If a reference-only journey exists, preserve all existing prose and EVIDENCE-REF pointers and append only the missing local steps/markers inside that existing section. Never create a second ## Validation Journey heading. Preserve all other description content — never overwrite or re-render it.
Step 8: Verify
Re-fetch the issue and confirm the section is present with at least one local [EVIDENCE: <artifact-type>: <name>] marker. An EVIDENCE-REF alone does not count.
When to Use This Skill
- Issue was created before the Validation Journey convention was established
- Issue was created manually without following
lisa-linear-createguidelines - Issue needs a journey added or updated based on implementation progress
- Before starting work on an Issue, to ensure verification steps are documented