shunta-sato/agent-instructions-playbook - Page 2

uiux-flow-preview

Use when a UIUX Pack needs a transition-map preview from ui_spec.json with pan/zoom, minimap, focus traversal, and Review Mode.

unit-test-design

Use when designing or reviewing unit tests: deciding test cases, boundaries, or coverage a change needs, choosing the E/S/H risk tier, deciding mock vs fake, judging whether a suite is over- or under-built, or fixing flaky/slow unit tests. Do not use for…

visual-regression-testing

Use when UI changes require repo-defined snapshot or visual-diff verification, baseline review, or a UI Visual Verification Report.

working-with-legacy-code

Use when touching code without reliable automated tests or with nondeterminism such as time, randomness, or I/O.

poc-workflow

Use for PoC, prototype, demo, or feasibility-spike construction answering one question with the cheapest artifact, on the research-mode substrate (a poc/ path or explicitly declared research task). Frames the question, exit criteria, and rigor floor first;…

test-driven-development

Use when doing TDD or when dev-workflow routes implementation through a Test List.

code-readability

Trigger only for requested readability review/cleanup, touched-code readability work involving comments, names, control flow, function shape, or test clarity, touched C++ headers, or dev-workflow routing to the C++ documentation gate. Do not trigger for…

japanese-tech-writing

Use when Japanese technical prose is drafted or revised in this repo: a PR title/body in 日本語, a Japanese review comment or reply, a Japanese issue, or Japanese content under plans/, reports/, or a README/doc. Applies house norms for formatting,…

requesting-code-review

Use when preparing a focused code-review request for a PR or diff after implementation evidence exists, especially to package scope, reviewer focus, PR URL, verification, known risks, and deferred work without deciding final submit readiness.

experiment-loop

Use for any evidence-bearing experiment in research mode, and when converting an unregistered exploration observation into citable evidence via a fresh confirmation on a new variation axis. Needs a hypothesis, a disconfirm predicate, and a command before…

design-balance

Use before feature-level implementation that adds two or more classes/modules, introduces a new layer/interface, or adds a second reason-to-change to an existing class/module. Do not use for function-only helper/API decisions or cross-boundary architecture…

architecture-decision-analysis

Use before implementation or during explicit design review when a cross-boundary technical decision requires comparing multiple architecture options against measurable quality drivers, risks, tradeoffs, and verification tasks. Do not use for ordinary…

concurrency-android

Android concurrency & background work: coroutines/dispatchers, structured concurrency, WorkManager vs Services/Foreground services, and OS execution limits. Use when modifying Android app code or background processing.

concurrency-core

Concurrency design patterns & safety workflow. Use when you introduce or modify concurrency (threads/async/callbacks/queues/locks), parallelize for performance, or need a clear shutdown/cancellation strategy.

concurrency-ros2

ROS 2 (rclcpp/rclpy) concurrency guidance: executors, callback groups, services/actions/timers, and deadlock-safe patterns. Use when modifying ROS nodes or callbacks.

error-handling

Use when a change defines or reviews failure contracts: boundary error translation, nullability/sentinel choices, retries/fallbacks, or API/user-visible failure behavior. Do not use for ordinary validation copy edits or pure logging changes with no…

observability

Use when a runtime behavior change needs diagnosable signals: async/background jobs, external calls, user-visible operations, or incident-prone flows. Do not use for docs-only or refactor-only changes with no behavior shift.

receiving-code-review

Use when handling received code-review feedback on a PR or diff, including requested changes, inline comments, approvals, non-blocking notes, and disputed suggestions. Separates accepted fixes, refutations, deferrals, clarification needs, and merge handoff.

staged-lowering

Use when implementing low-level or strict-constraint code (kernels, SIMD/intrinsics, alignment/padding rules, codegen/DSLs, strict ABI or hardware APIs), or when direct implementation repeatedly fails to compile/test.

implementation-economy

Use before and after normal/high-risk implementation when a complexity budget is needed: declare new classes/helpers/wrappers/indirection/estimated lines, justify each new abstraction, and delete or inline abstractions that are not worth their weight. Do not…

performance-review

Use when non-embedded application code changes request paths, render paths, input-proportional collection processing, loop I/O, N+1 queries, repeated serialization/allocation, serial awaits, or cache/memoization decisions. Declare hot paths, complexity, I/O…