Repository navigation
docs: require full-app PR screenshots and document fork upload paths - #21076
kyleseaman merged 1 commit into
Conversation
7d90f2e to
8925bdd
Compare
UX Review (Opus 5.5, fork) — ⏭️ skippedRevision |
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Docs-only guidance change, and it matches the gate: [DESIGN-REVIEWED] b4777f4 Description read[DESCRIPTION-READ] 67160f22a264ac726f7b58374a6b273e88df5d827d99b49522ce9833280d975d That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. This is a docs-only change whose items all serve the frozen Goal, and the defect has a linked issue (#21071). What this change shipsInventory (7 items) — 7 justifiedIntent: help PR authors, fork contributors included, post screenshot evidence that review accepts: full-chrome frames and a programmatic upload path. This is a FIX to the guidance.
[FIRST-PRINCIPLES-REVIEWED] b4777f4 Description read[DESCRIPTION-READ] 0a19d3c880e4af115d90b54ad48c44f9bbe306ce2077a1cc152e810bd4fcd91b That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Research: can a fork author's screenshot be made review-admissible, and what would
|
8925bdd to
36cffcd
Compare
36cffcd to
965c545
Compare
|
Addressed the blocking finding the GPT 6.1, Opus 5.5, and First Principles gates all raised at Finding (all three gates agreed): the template and the prepare-pr skill recommended pushing screenshots to an unrelated fork branch and linking
So a fork author following that advice supplies evidence that never reaches a lane, and the UX/design review blocks the UI change for a missing screenshot. Fix (pure docs, 3 insertions / 6 deletions):
I also corrected two description inaccuracies First Principles flagged: the body no longer claims a hidden This clears the blockers' stated condition: neither file recommends 🤖 Agentic transparency
|
|
Update — gates re-ran green at The fix push did dismiss the earlier approval, so the PR is back to needing a maintainer to approve the fork CI run on this head and a re-approval. That's the only thing left. |
iamwhatever
left a comment
There was a problem hiding this comment.
Request changes at 6d19da0: the prepare-pr guidance now gives fork contributors two conflicting instructions.
In kirocrew-prepare-pr/SKILL.md the kept bullet still says "Push access is required; without it, commit the evidence" (L683). The new bullet right below it says to prefer the fork-issue upload and commit only as a last resort. references/rationale.md still states that a fork contributor has no CLI path to an attachment at all (L535). An agent following the bold titles will still commit binaries, which is the outcome this PR is meant to prevent. The Design and First Principles notes on this head both raise this and have no reply. Smallest fix: reword the pinned bullet title and its test pin together so there is one order of preference, and update rationale.md L535 to match.
Also blocking merge: Fork workflow-change guard fails on this head because the PR edits .github/PULL_REQUEST_TEMPLATE.md. A maintainer must review that template change and apply allow-fork-workflow-change. The template edit itself is prose only.
— crew-pr-reviewer (r130)
|
Addressed @iamwhatever's review (crew-pr-reviewer r130) at head The finding was real. My earlier revision left two conflicting instructions for a fork contributor:
Fix — one order of preference, stated once and consistently:
Reworded the SKILL.md bullet title + body to carry that order, and corrected On the Fork workflow-change guard failure — that one is structural, not fixable from the fork. The guard fires fork-only when a PR touches any non-baseline The template edit is prose only; happy to adjust wording further if you'd prefer a different phrasing of the preference order. 🤖 Drafted with agent assistance; reviewed and posted by @tmack8001. |
Security Scope Review (fork) — 🔴 BLOCK (blocking)Which legitimate operations does the review scope was never resolved: the generate job did not finish (it timed out, failed or was cancelled), so no leg ran; its log names the step that stopped No |
|
@iamwhatever — thanks for the careful read. I've addressed both findings at the current head ( What changed:
Full disposition with the before/after is in #21076 (comment). Heads-up on the one thing I can't do from the fork: re-requesting your review formally (and approving the fork CI run on this head) both need maintainer access, so this is parked on you there. Appreciate it. 🤖 Posted by an AI agent on Trevor's behalf. The analysis and edits above were produced autonomously; a human has not independently re-verified every claim. Push forced to |
c52e100 to
aaf42f5
Compare
aaf42f5 to
b4777f4
Compare
|
Stale-PR cleanup check: this PR is approved (kyleseaman, 2026-11-19) and every CI job passes on head |
Problem / Motivation
Goal: Make KiroCrew's own PR-screenshot guidance say two things it currently omits: show the full application chrome, and how a fork contributor without upstream write uploads evidence programmatically.
Two gaps keep biting PR authors (human and agent). PR review (the UX lane) wants the changed surface in full application chrome, but
web-verifysteers toward an element-only crop; a pane-only crop then draws a "not the real pane" finding. And a fork contributor without upstream write is told only to drag in the web UI or commit the binary — the drag path is often unavailable and committing is discouraged, while the working programmatic path goes undocumented.Why it matters
Screenshot evidence is how a UI change is reviewed. A cropped frame fails review for lack of context; a contributor with no upload path either commits a binary into history or stalls. Both recur because the guidance the author reads does not cover them.
Not a goal
raw.githubusercontent.comURLs are explicitly called out as NOT evidence, not offered as an upload option.ci-and-reviews.md.What changed (motivation → approach → change)
The additions are minimal and in-scope. In
.github/PULL_REQUEST_TEMPLATE.md, the existing Screenshots guidance comment is rewritten to carry the full-chrome rule and the fork upload path (the fork-issue--attachroute that mints admissibleuser-attachmentsURLs), and the web-UI drag is noted as not always available.web-verifygains a one-clause full-chrome note with its pinned wording byte-identical.kirocrew-prepare-prgains the full-chrome note and its fork-evidence bullet is reworded into a single order of preference (fork-issue--attach→ web-UI drag → commit only as last resort), andreferences/rationale.mdis corrected to match — it previously claimed a fork contributor had no CLI attach path at all. Every substring the gate tests pin on the prepare-pr bullet is preserved, so the pins still pass.The documented upload paths, in order of preference: upload via
gh issue create --attachon your own fork (where you are admin, so--attachworks) which mints account-scopedgithub.com/user-attachments/assets/...URLs that render cross-repo, keeping that issue as a reusable holder; web-UI drag when available; commit into the PR branch only as a last resort. Rawraw.githubusercontent.comURLs are documented as NOT admissible evidence —pr-attachment-evidence.shadmits onlyuser-attachmentsURLs — so they are not offered as an upload path.Backwards compatibility
Compatible: documentation-only; no code, API, or data shape changes.
No test-pinned string moved: every substring the gate tests pin on the committed-evidence bullet (ceiling, format list, SVG exclusion,
--attachfigures) is preserved after the reword, so the gate tests that pin them still pass.Tests
No new automated test. The existing
test/test_pr_quality_gates.py,test/test_pr_hygiene_guidance.py, andtest/test_fork_pr_description_workflow.pypin the committed-evidence wording and all still pass — the reworded bullet preserves every pinned substring.scripts/docs-lint.shpasses.Manual verification
N/A — documentation change; the gate tests above and docs-lint are the verification, and the fork-attach path was exercised live this session (it produced the account-scoped
user-attachmentsURLs now embedded on #21068).Screenshots / video
Why no screenshot: documentation-only change; no rendered UI surface is touched.
Related Issues
Closes #21071
Pattern harvest
Not generalizable: a one-time correction to specific guidance docs, not a defect class with a detectable pattern.
Checklist