Repository navigation
feat(skills): add dev-desk-check and qa-review browser QA foundation skills - #31
Draft
vitor-rangel-vinta wants to merge 14 commits into
Draft
vitor-rangel-vinta wants to merge 14 commits into
vitor-rangel-vinta wants to merge 14 commits into
Conversation
…rails - write-gate rule 6: restore the spec's second sentence, so the write ledger itself is told to carry opaque IDs rather than field values under phi - escalation section: distinguish the agent flipping a flag itself from proposing the command and waiting, so it agrees with rule 7's propose-and-wait - dev-server pitfall: starting anything is local-only and asks first - screenshot resolution: captures land under the report dir, required (not conventional) under client or phi
…on and share-scope qualifiers to qa-review template
Renames the engineer-facing browser QA skill and every identifier that
names it: the foundation_skills enum entry, run_options.qa-frontend, the
shared skills.qa-frontend config block that qa-review also renders from,
and the template file itself. The {{QA_*}} placeholder names are
unchanged - they are shared with qa-review and describe the domain, not
the skill.
Adds "desk check this branch" to the template's trigger phrases so the
new name is discoverable.
… plan-only reference
Final review findings:
- The dev-desk-check intro linked ../add-e2e-test/SKILL.md and
../create-qa-use-cases/SKILL.md unconditionally. Both are independent
opt-ins, so the links dangle in any project that did not enable them.
The conditional links already live where they belong, inside
{{QA_E2E_IMPACT_BLOCK}} and {{QA_USE_CASES_BLOCK}}; the intro now names
the skills without linking them. The template ships zero links.
- Verification demanded the report state the viewport, but the Phase 8
report skeleton had no field for it. Added Viewport to the header line,
matching the Phase 5 instruction to say which viewport the run used.
- The derive-time portability check cited "Task 3 Step 10", a numbering
that exists only in the planning document and has no referent in the
shipped package. Describes the check instead.
…preflight conflict Rendering the skill into a real project surfaced three defects the branch review missed: - Phase 3's fixed 'Fixed order' line announced a services step and gave a services-only rationale for the ordering, so a project declaring no services shipped a phase advertising a step it would never run. The frontmatter description over-promised the same way. Services ordering and its rationale move into QA_SERVICES_BLOCK, which vanishes with them. - De-linking the intro's two conditional-skill pointers removed the broken paths but left the broken references. The framing now describes the situation rather than naming add-e2e-test and create-qa-use-cases; the conditional blocks still name them where that is accurate. - QA_PREFLIGHT_BLOCK's contract told the renderer both 'no curl preflight' and 'probe base_url and stop' for any environment with edge_proxy set and frontend_start absent — every remote environment. edge_proxy now explicitly shapes the whole entry, the frontend probe is specified for the non-proxied case, and frontend_start governs starting rather than probing.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this adds
Two new opt-in, template-rendered foundation skills for browser QA, plus the config contract they read.
dev-desk-check— the engineer pathDrives a real browser through the running app the way a user would, judges what actually renders, and leaves evidence someone who wasn't in the session can trust. The manual counterpart to
add-e2e-test's automation, not a substitute.Q.A.section.implement-plan's phase gate — a browser pass per phase is too slow, the same reasoning that keepsrun_options.run_e2eoff.qa-review— the portable pathThe same browser walk and the same report shape for product managers and designers, with git, diffs, dev servers, service probes, PR edits and database access stripped out. Rendered self-contained: zero relative links, zero repo-dependent commands, no engineer jargon — so an engineer can hand over the single
SKILL.mdand it works for someone with no checkout, no terminal and no repo.Enforced at derive time by a portability check in
vinta-derive-skills, whose jargon term set is deliberately wider than the template-only check, because jargon can arrive through a rendered block even when the template itself is clean.One shared config block
Both skills render from
skills.dev-desk-checkand are gated by independentfoundation_skillsentries — a project can take the engineer path alone, the review path alone, or both.Guard rails are data, not prose: a project declares its policy per environment and the rendered skill enforces exactly what it was given.
Guard rails baked into the contract
auth.accounts[].whereis a pointer to where a secret lives, never the secret.auth.loginis a single-valued enum (manual) on purpose — the schema gives a project no way to express an automated login. The agent never types a password, in any environment.data_sensitivity: phithe report and the write ledger carry opaque ids only, andphiblocks the shareable artifact deliverable outright.writes: free.Files
schemas/vinta-ai-workflows-config.v1.schema.jsonfoundation_skills.dev-desk-check+.qa-review,run_options.dev-desk-check,skills.dev-desk-checkskills/vinta-derive-skills/resources/dev-desk-check-template.mdskills/vinta-derive-skills/resources/qa-review-template.mdskills/vinta-derive-skills/SKILL.mdskills/vinta-bootstrap-ai-tools/SKILL.mdskills/vinta-analyze-codebase/SKILL.mdfoundation-shapeclassifier listskills/vinta-update-project-skills/SKILL.mdqa-reviewre-renders on a config change, not just a template changeREADME.md,CHANGELOG.md0.7.0sectionpackage.jsonis untouched —dev-skills/releaseowns the version bump. TheCHANGELOGheading carries a literalYYYY-MM-DDplaceholder for the same reason.Notes for review
qa-frontendthrough most of its development; the last commit renames it todev-desk-checkacross every identifier (enum entry, config block, template file, frontmatter, H1, report line). The{{QA_*}}placeholder names are intentionally unchanged — they are shared withqa-reviewand name the domain, not the skill.Review status
A whole-branch review returned three findings, all fixed in the last commit and confirmed resolved by a scoped re-review:
add-e2e-testandcreate-qa-use-casesunconditionally. Both are independent opt-ins, so in a project that enabled neither, the rendered skill shipped two links to directories that do not exist — and the placeholder contract in this same package already makes exactly those two links conditional. The intro now names both skills without linking them; the conditional links stay where they belong, inside{{QA_E2E_IMPACT_BLOCK}}and{{QA_USE_CASES_BLOCK}}. The template now ships zero markdown links, which puts it under the same grep that guardsqa-review.## Verificationrequired the report to state the viewport used, but the report skeleton had no field for it. Added**Viewport**to the skeleton header, matching the phase instruction that already asks for it.Verified clean by the review: all placeholders match 1:1 between both templates and the placeholder table in both directions; the bootstrap interview's example YAML validates against the schema field-by-field, including
additionalProperties: false; no write-gate rule is shipped twice (once as prose, once via a rendered block); and none of the four guard rails above has a bypass reachable from a schema-valid config.Known-minor, deliberately deferred
--writes=allowflag wording is self-cancelling. Traced: it never actually relaxes anything — confirmation is unconditional underwrites: confirmand the flag is refused underforbidden— so this is a dead flag, not a guard-rail hole.local" instead of deriving from the declared environments. Schema and template agree word-for-word, so it is a documented limitation rather than a contradiction.frontend_startfollow-up states the mechanism but not the cost of leaving it blank.Dogfooding pass — rendered into a real project
Rendered
dev-desk-checkintoaltlegal/com(TypeScript/React frontend that already carries a hand-writtenqa-frontendskill) from a schema-valid config, withservicesanddesign_sourceomitted so both conditional-strip paths were exercised. Three more defects surfaced, all confirmed in the rendered output and fixed here:servicesdeclared the### Services pre-checksection vanished correctly, but the fixed prose above it still announcedservices → frontend → backend → data preconditionsand justified the ordering with a services-only rationale. The frontmatterdescription:over-promised the same way. Services ordering and its rationale now live in{{QA_SERVICES_BLOCK}}, which vanishes with them — same class as the dangling-link blocker above, one region further up.create-qa-use-cases"writes flows in user language". The framing now describes the situation instead of naming sibling skills; the conditional blocks still name them where that is accurate by construction.{{QA_PREFLIGHT_BLOCK}}'s contract contradicted itself. It told the renderer both "No curl preflight — the browser is the preflight" (whenedge_proxyis set) and "Probe<base_url>and stop" (whenfrontend_startis absent) — and those are the same environment for every remote environment a normal project declares. The frontend probe was also never specified, only the backend one, which is where the conflict hid.edge_proxynow explicitly shapes the whole entry and overrides every probe instruction below it;frontend_startgoverns starting, not probing.Left open, worth a decision rather than a quiet fix:
<!-- rendering note: -->comments have no documented disposition. Nothing says to strip them, and an unstripped one would putskills.dev-desk-check.feature_flagsinto a renderedqa-review— which the portability check greps for.environments.<name>.base_urlis required with no way to say "supplied per run". com's Azure pre-production slot has no fixed URL, and Step 0 tells the agent never to open a URL that is not in the table.skills.dev-desk-checkhas no free-form escape hatch.skills.write-unit-test.additional_conventions[]already solves this shape; without it, repo-specific knowledge (a changed-path → reachable-surface map, a feature-flag discovery grep) cannot reach the render, which is most of what the hand-written skill has and this one does not.Still draft
Left as a draft for your call on the deferred items above and on the
0.7.0release date, which is a literalYYYY-MM-DDplaceholder untildev-skills/releaseruns.