ai-runbook-jh

Validates a change in the browser using the project's sanctioned browser-inspection MCP, navigating pages, inspecting DOM/console/network, capturing screenshots. Use when the user says browser check, validate locally, test this in the browser, check the console, does this look right, or check this page. Apply when validating any frontend change even if the user does not say 'browser check'.

Writes closure notes for a completed ticket/issue. Use when the user says close this ticket, write closure notes, ticket is done, wrap up this ticket, or I'm closing [issue-ref]. Apply when the user is finishing a ticket even if they don't say 'closure notes'.

Writes QA steps for a ticket or PR. Use when the user says write QA steps, add testing instructions, how do I test this, write the QA section, or what should QA check. Apply when the user is preparing a ticket or PR for review and needs test instructions.

Summarizes commits into a PR description, changelog, or sprint summary. Use when the user says summarize these commits, write a PR description, what changed in this branch, write release notes, or sprint summary. Apply when the user shares a git log and wants a human-readable summary.

Deeper refinement of a ticket/issue to advance it toward Ready for Estimation or Ready for Dev. Use when the user says refine this ticket, prep this ticket, get this ready for estimation, write up the ticket body, this ticket needs more detail, or fill in the AC. Apply after triage when a ticket needs full acceptance criteria, implementation details, and LOE-readiness.

Critically reviews Drupal PHP, Twig, SCSS, or config for correctness, security, performance, and project standards. Use when the user says review this Drupal code, critique this, is this correct, check my service/hook/template, or what's wrong with this. Apply when the user shares backend Drupal code and wants a quality check even if they don't say 'review'.

Peer reviews a frontend change; templates, styles, JavaScript, or component files; before merge. Use when the user says review this, peer review, look at my frontend change, is this ready to merge, or review this PR. Apply when the user shares frontend code and wants a second opinion even if they don't say 'peer review'.

Writes a structured handoff note at the end of a work session. Use when the user says handoff, write a handoff, I'm done for the day, end of session, picking this up later, or hand this off. Apply when the user is wrapping up work even if they don't say 'handoff'.

Writes the implementation details checklist for a ticket. Use when the user says write up the implementation details, add implementation details, or what would I do for this ticket. Produces a practical dev checklist of what to actually do, not a narrative of what was done. Reads project-specific values (tracker markup, stack, tooling) from the active project contract.

Writes an implementation plan for a ticket/issue. Use when the user says plan this ticket, plan this issue, break this down, what's the approach, stub out this ticket, or I need to write up a ticket. Apply when the user wants to think through a ticket/issue before starting work.

Checks an implementation for unnecessary complexity and suggests the simplest approach. Use when the user says is this too complex, am I over-engineering this, simplify this, is there a simpler way, or do I need all of this. Apply when the user shares code and seems uncertain whether the approach is too involved.

Writes a lessons-learned note after completing a ticket, sprint, or project phase. Use when the user says lessons learned, retrospective, what did we learn, what went wrong, what would I do differently, or I just finished this and want to reflect. Apply at the end of any significant piece of work.

Organizes unstaged changes into clean logical commits ready to push, following the active project's commit conventions. Use when the user says organize commits, stage my changes, help me commit, prep for a PR, or my changes are a mess. Prefer squash-commits when the user only wants to squash existing commits, not organize working tree changes.

Checks whether a new implementation follows existing codebase patterns, read from the active project contract. Use when the user says does this follow our patterns, is this consistent, how do we normally do this, check my approach, or am I doing this the right way. Apply when the user shares new code and wants to know if it fits the project conventions.

First-touch assessment of a ticket/issue, decline/defer/keep, fill minimum required fields, set initial priority, tag as reviewed. Use when the user says triage this, first pass on this ticket, quick assess this, or shares a ticket/issue they're seeing for the first time. The goal is a fast keep/cut decision, not a full refinement.

Audits a page or component for frontend performance issues, render blocking, asset size, caching, Core Web Vitals. Use when the user says performance audit, this page is slow, check performance, Core Web Vitals, why is this loading slowly, or check my assets. Apply when the user wants to find or fix frontend performance problems.

Reviews written content for tone, clarity, and appropriateness. Use when the user says check the tone, does this sound right, review this writing, is this too formal, rewrite this, or shares a commit message/PR description/ticket comment and asks for feedback. Apply when the user wants a second opinion on any written communication.

An honesty gate that makes AI back up its claims with real evidence instead of presenting guesses as fact. Use at all times as a background behavior, invoke explicitly when the user says show your work, prove it, how do you know that, evidence check, what's your source, back that up, or when the AI is recommending a course of action. Apply as a cross-cutting self-check before presenting technical claims, recommendations, or architectural guidance.

Pre-flight checklist before pasting context into an AI prompt. Use at the start of an AI session, before pasting user data, before sharing screenshots, before authentication-adjacent work, or when the user says is this safe to share, can I paste this, security check, AI safety, will this contain PII. Apply whenever the next action involves sending substantive content to an AI tool.

Audits a page, component, or template for WCAG 2.1 AA / Section 508 compliance. Use when the user says accessibility audit, check a11y, find accessibility issues, is this accessible, Section 508 check, or review this for accessibility. Apply when the user shares a page or component and wants compliance validation even if they don't say 'audit'.

Writes a well-formed git commit message. Use when the user says write a commit, commit message, what should my commit say, help me commit, or draft a commit. Apply even when the user just says 'commit this' or shares a diff without explicitly asking for a message.

Produces a component design spec (variables, markup sketch, states, a11y notes) against the active project's design system, not working code. Use when the user says design this component, how should this look, plan this UI, sketch this out, what component should I use, or review this design. Apply before implementation to align on structure.

Reviews or plans responsive behavior across mobile, tablet, and desktop breakpoints. Use when the user says check responsiveness, does this work on mobile, responsive review, test at different viewports, or how does this look on small screens. Apply when the user shares a component or layout and wants breakpoint validation.

Outputs the appropriate Definition of Done checklist for a ticket type (FE, BE, DevOps), read from the active project contract. Use when the user says DoD checklist, definition of done, append the DoD, what's the checklist, or when another skill (ticket-refinement, qa-steps, issue-closure-notes) needs to append the DoD. Single canonical source so the DoD list doesn't drift across artifacts.

Squashes WIP commits into clean commits before merge. Use when the user says squash commits, clean up commits, squash these, combine commits, or I have a bunch of WIP commits. Apply when the user wants to tidy history before opening a PR even if they don't say 'squash'.