repoprompt-workflows

Use FIRST when work is about to start on any repo — a bug is reported, a feature/enhancement is requested, an open question or design decision is raised, someone asks to "track"/"log"/"add a ticket for" something, asks what is open / in-progress / done, or an agent is about to implement a change that has no tracking item. Creates or updates one tracking item in GitHub Issues when origin is GitHub, or a committed file backlog under .agents/issues/ otherwise; temporary GitHub access failures stop with diagnostics instead of silently creating a second ledger. Applies repo taxonomy and links detail files.

Use when creating, modifying, reviewing, or deciding whether to add tests, fixtures, mocks, integration tests, end-to-end tests, smoke tests, or test plans in any codebase or language, including regression tests for bug fixes. Guides agents to choose the right test layer, avoid low-value tests, and verify meaningful behavioral oracles.

Use when reconciling documentation to code changes or auditing documentation drift in a repo. Applies whenever the user asks to update docs after code changes, check whether docs match code, run a documentation audit, or produce doc drift reports; defaults to dry-run proposals and requires explicit apply before writing.

Use for a strict, quality-only structural review that hunts for dramatic simplifications, not local cleanup. Trigger on requests for a harsh maintainability audit, a deep code-quality review, or where complexity can be deleted rather than rearranged — giant files (>1k lines), spaghetti branching bolted onto unrelated flows, unearned wrappers/pass-throughs, logic leaking across layers, and missed "code judo" moves. Use as one lens in a multi-lens review, or standalone. Quality-only; pair with a correctness lens for behavior bugs.

Use when deciding how much review effort a change warrants — quick, standard, or deep — picked from the change's size, spread, risk, and blast radius. Reach for it whenever someone asks how thoroughly to review a PR, branch, or diff, or whether a quick pass or a deep review fits a given change. It only sizes the effort — it does not perform the review, choose lenses, or triage findings. An explicit quick/standard/deep choice overrides detection.

Use when producing, consuming, triaging, or revalidating code-review findings — review artifacts, P0/P1 findings, fix loops, and "is this finding real or fixed?" decisions, in any repo. Enforces structured evidence, prompt-grounding, a revalidation gate that refuses model-only "fixed", and stable-signature triage/dedup/rerank. This governs findings you already have — it does not discover them or size the review.

Use when closing a spec-driven feature/issue or auditing whether an implementation actually matches its spec. Given a spec path, emits a section-by-section conformance matrix mapping every scenario and Proposed Surface element to Conformed (with file:line/test evidence), Diverged (what + why + both sides), or Not-built, plus an audited/unreconciled coverage proof. Distinct from document (doc-vs-code drift) and spec-quality (spec well-formedness) — this is spec-vs-implementation, independent of test pass/fail.

Use before implementation when a Spec and Deep Plan must be checked for coding readiness. Applies a deterministic go/no-go gate for missing inputs, unresolved spec blockers, incomplete ordered plans, spec-plan contradictions, task-to-scenario traceability, scenario-to-test layer mapping, risk/rollback requirements, and first-safe-task selection; a blocked verdict authorizes no tests, code, or implementation delegation.

Use when drafting, reviewing, repairing, or validating scenario-based specs, product specs, implementation specs, Proposed Surface sections, Given/When/Then scenarios, Open Questions, or spec-quality checklists. Helps keep specs contract-level, observable, non-redundant, grounded in repo context, and free of implementation planning.

Use when finishing a user-facing/frontend feature, to verify it actually works for the person it's built for — not just that automated tests pass. Drives the real rendered UI via automation — browser tools (e.g. chrome-devtools) for web/HTML, platform UI automation for non-HTML native UI — through the actual user workflows, screenshotting each step and checking console/network, to catch defects unit/contract tests miss. A human hand-off is the optional gold standard. Distinct from test-quality (automated tests), spec-conformance (spec vs implementation), and review (code review).