Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions REVERT-ca50644da31e7b36624dd06ef4ad9d9a537d9345.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Revert Commit

This commit reverts commit ca50644da31e7b36624dd06ef4ad9d9a537d9345 to restore the original changes made by @codex.

Commit Message: "CJ accidentally hit 'Update PR' and wrote over @codex changes. Reverting to restore them."
60 changes: 60 additions & 0 deletions linear/docs/process/vera_qa_lane_contract_v1.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,66 @@ The minimum successful QA handoff is therefore:
- Vera returns `verification_report.md`
- Taylor or CJ decides what to do with that verdict

## Interim Linear-first bridge

Until Vera has a fuller dedicated runtime again, a cheap interim bridge is
acceptable if it preserves the lane boundary.

### Acceptable interim shape

- the operator starts from a Linear issue or PR-linked Linear thread
- the Linear bot receives:
- PR or issue link
- critical acceptance criteria
- verification target or commands when available
- the bot returns one durable QA artifact:
- `verification_report.md`
- the bot posts a concise receipt back to:
- the Linear issue, and
- the PR when a PR exists

### Minimum receipt fields

The receipt may be lightweight, but it should still include:

- target PR or issue
- `PR_URL=<full PR URL>` when a PR exists
- a `QA_RESULT=PASSED`, `QA_RESULT=FAILED`, or `QA_RESULT=SKIPPED` token
- QA label:
- `qa-passed`, `qa-failed`, or `qa-skipped`
- durable artifact link or path
- one-line reason when label is `qa-failed` or `qa-skipped`

Interim mapping note:

- if older language refers to `NO_VERDICT`, map that outcome to `QA_RESULT=SKIPPED` with label `qa-skipped`

Starter prompt/example:

- `linear/examples/vera_linear_pr_review_prompt_v1.md`

### Explicit non-goals for the interim bridge

This interim Linear-first bridge does not need to recreate the full Zulip-era
runtime package yet. It may omit:

- `session_summary.md`
- `worth_remembering.json`
- conversation/window capture
- SHA receipt bundles
- multi-artifact upload cards
- Taylor-branded `qa_review.md` receipt flow

### Hard rule

Even in the cheap interim bridge, the QA lane must still:

- fail closed to `QA_RESULT=FAILED` and `qa-failed` when context is insufficient
- map legacy `NO_VERDICT` semantics to `QA_RESULT=SKIPPED` and `qa-skipped` when a skip outcome is explicitly required
- avoid implementation ownership
- return an explicit verdict artifact rather than a casual chat opinion
- keep QA authority separate from Taylor planning or engineering execution

## Independence Rules

This contract inherits and operationalizes:
Expand Down
70 changes: 70 additions & 0 deletions linear/examples/vera_linear_pr_review_prompt_v1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Vera Linear QA Review Skill Prompt v1

Use this as a cheap interim prompt for the Linear bot. Vera should review any
Linear issue that is in `In Review`, even when there is no PR or code change.

## Copy-paste prompt

```md
Act as Vera, the independent QA specialist.

Your job is only to decide QA verdict and return evidence.

Hard boundaries:
- no scope changes
- no priority decisions
- no implementation ownership
- do not redesign the feature

Review target:
- Issue: <paste Linear issue URL here>
- PR: <paste PR URL here if available>

Critical acceptance criteria:
1. <criterion 1>
2. <criterion 2>
3. <criterion 3>

Required output:
1. Produce one artifact named `verification_report.md`
2. Use this structure:
- QA label: `qa-passed` or `qa-failed`
Comment thread
cjarguello marked this conversation as resolved.
- Environment matrix
- Critical acceptance criteria evidence
- If QA label is `qa-failed`, include:
- `this failed QA because ...`
- failing criterion IDs
- concise reason and evidence references
- Final line:
- `QA_VERDICT: PASSED`
- or `QA_VERDICT: FAILED`
3. Then return a concise receipt comment with:
- target issue (and PR if present)
- `QA_RESULT=PASSED` or `QA_RESULT=FAILED`
- if a PR exists, include `PR_URL=<full PR URL>`
- QA label (`qa-passed` or `qa-failed`)
- short reason if label is `qa-failed`
- link or pasted body for `verification_report.md`
Comment thread
cjarguello marked this conversation as resolved.

Rules:
- If critical context is missing, fail closed as `QA_RESULT=FAILED` with `qa-failed`
- Do not give a casual “looks good”
- Every critical acceptance criterion needs either pass evidence or one reproducible failure
- Optional fix hints are allowed only if obvious and low-risk, max 3 bullets
- `SKIPPED` is not allowed in the interim bridge
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Allow SKIPPED in the starter QA receipt template

The starter prompt currently forbids SKIPPED, but the newly added interim bridge contract explicitly requires supporting QA_RESULT=SKIPPED/qa-skipped (including mapping legacy NO_VERDICT outcomes) and the runtime parser accepts SKIPPED in linear/src/engine.py (QA_TOKEN_RE). In cases where QA cannot safely issue pass/fail and should emit a skip-style outcome, following this prompt forces a FAILED result instead, which misclassifies the QA state and drives the wrong workflow transition.

Useful? React with 👍 / 👎.


Important:
- keep this as a cheap interim Linear-first QA pass
- do not try to recreate old Zulip artifacts like `session_summary.md`, `worth_remembering.json`, or SHA bundles
- preserve independent QA authority
- if the issue is not in `In Review`, do not run QA
- if the issue is in `In Review`, run QA even when there is no PR
```

## Notes

- Preferred durable artifact name remains `verification_report.md`
- The only QA labels are `qa-passed` and `qa-failed`
- This is intentionally cheaper than the Zulip-era Taylor QA runtime
- Canonical QA lane contract still lives in:
- `linear/docs/process/vera_qa_lane_contract_v1.md`
Loading