Design and review AI review surfaces, acceptance controls, rejection flows, loading and failure states, and implementation handoff for expansion and decomposition in this AI-assisted task execution app. Use when changing capture review flows, task detail AI workspace behavior, partial acceptance controls, pending or failed suggestion presentation, or the UI composition of expand or decompose actions. Do not use for AI contract design, accepted field enums, canonical write payload design, prompt-only changes, or purely visual styling without review-flow impact.
Use this skill to make AI review flows clear, selective, and safe. Keep review UI understandable, keep pending suggestion sets visibly non-canonical, and make acceptance targets obvious before any committed data changes.
Use this skill when the task changes:
Do not use this skill as the primary guide when the task is:
Use instead when the main risk is acceptance semantics or write payloads.
ai-acceptance-designerKeep this skill aligned with AGENTS.md:
task detail as the central AI workspaceboard, list, and focus as execution surfaces, not the AI planning engineRead these repo documents before changing behavior, in this order:
AGENTS.mddocs/product/mvp-scope.mddocs/domain/todo-kanban-rules.mddocs/domain/capture-expand-decompose-lifecycle.mddocs/architecture/task-model-and-reorder-contracts.mddocs/architecture/implementation-bridge.mddocs/architecture/ai-api-and-structured-output-contracts.mddocs/product/implementation-roadmap.mddocs/product/ai-surface-and-user-flows.mddocs/qa/kanban-checklist.mddocs/qa/ai-evals-checklist.mdInspect these implementation paths before editing:
shared/ai/contracts.tssrc/components/CaptureDetail.tsxsrc/components/CaptureExpansionPanel.tsxsrc/components/TaskDetail.tsxsrc/components/TaskExpansionPanel.tsxsrc/components/TaskDecompositionPanel.tsxsrc/App.tsxsrc/lib/api/ai.tssrc/features/ai/format.tssrc/features/ai/model.tssrc/features/ai/store.tssrc/features/subtasks/api.tssrc/features/subtasks/model.tssrc/features/subtasks/store.tsStart with repo inspection before proposing changes.
Useful commands:
rg -n "Expand with AI|Decompose with AI|Reject latest|accepted|partially_accepted|rejected|failed" src docs
rg -n "suggestionSet|acceptedFields|onAccept|onReject|isLoading|error|aiActionError" src/components src/App.tsx src/features
rg -n "CaptureExpansionPanel|TaskExpansionPanel|TaskDecompositionPanel|TaskDetail|CaptureDetail" src
rg -n "subtask|next_actions_notes|description_notes|normalized_title" src shared docs
Use the search results to identify:
Keep these meanings precise:
capture item is intake statetask is committed execution worksubtask is a child execution unit under a task, not display-only metadataAI suggestion set is reviewable output, not canonical dataSubtask handling in review flows must stay explicit:
Design review UI around the real acceptance targets, not generic "apply AI" actions.
Source surface:
CaptureDetailCaptureExpansionPanelCurrent implementation path:
CaptureExpansionPanel selects normalized_title and/or description_notesApp.tsx currently accepts the suggestion and creates the committed task in the same flowcapture item is archived as part of that successful acceptance pathUI obligation:
Source surface:
TaskDetailTaskExpansionPanelAcceptance targets:
normalized_title into task.titledescription_notes into task.description through the appended AI expansion blockDo not imply that task expansion changes status, position, or board column.
Source surface:
TaskDetailTaskDecompositionPanelAcceptance targets:
subtasks into canonical child tasks under the selected parent tasknext_actions_notes into the parent task description through the appended AI decomposition blockDo not imply that decomposition creates top-level board tasks or a new workflow stage.
Treat these as separate UI problems:
Meaning:
Expand with AI or Decompose with AI failed before a reviewable suggestion set became usableTypical ownership:
Meaning:
Typical ownership:
App.tsxDo not collapse these into one generic error state unless the user experience remains equally clear.
Classify failures before designing the UI:
config_error: missing API key or disabled backend; show actionable setup copy and keep source context intactvalidation_error: client or server rejected the payload; do not suggest retry until the invalid input changesprovider_or_model_error: model call failed or timed out; allow retry from the same review surface when safeschema_or_parse_error: the model response was unusable for the current contract; do not render partially trusted suggestions as reviewable outputaccept_mutation_error: accept failed after a reviewable suggestion existed; keep the suggestion visible and preserve selected fields when practicalreject_mutation_error: reject failed; keep the suggestion reviewable and do not pretend it was discardedpersistence_error: state could not be saved after a client or server action; explain whether the visible state is persisted or only localFor each class, define:
Write down:
capture_item or taskexpansion or decompositionEnforce these rules:
Cover these states explicitly:
For each state, define:
Use these ownership boundaries:
CaptureExpansionPanel and TaskExpansionPanel own expansion review controlsTaskDecompositionPanel owns decomposition review controlsCaptureDetail and TaskDetail compose the surrounding surfaceApp.tsx orchestrates accept or reject state transitions and shared mutation outcomessrc/lib/api/ai.ts owns typed client callssrc/features/ai/* and src/features/subtasks/* own suggestion and accepted-child data helpersSearch for shared review primitives before adding more duplicated panel logic. In particular, compare:
Do not collapse all review behavior into App.tsx if a panel can own the local interaction state.
Do not preserve duplication by default when two panels share the same review behavior.
Do not push provider-specific behavior into review components.
When the change affects:
docs/product/ai-surface-and-user-flows.mddocs/qa/ai-evals-checklist.mddocs/qa/kanban-checklist.mdAdd or adjust tests for:
config_error, validation_error, provider_or_model_error, schema_or_parse_error, and persistence_error when the UX distinguishes themEscalate to another skill when needed:
ai-acceptance-designer when the main change is in acceptance semantics or write payloadstask-domain-guard when the main change is lifecycle or board semanticsui-designer when the task is broader interaction design beyond AI review surfacestest-automator when the main gap is regression coveragebrowser-debugger for browser-only focus, scrolling, overlay, or interaction bugsWhen using this skill, produce these sections in order:
SurfaceState MatrixError Taxonomy And Recovery MatrixAcceptance TargetsImplementation PathUser RisksDocs To UpdateRegression CoverageOpen QuestionsFill every section. If a section has no changes, say none.
For State Matrix, include at least:
For Error Taxonomy And Recovery Matrix, classify at least:
config_errorvalidation_errorprovider_or_model_errorschema_or_parse_erroraccept_mutation_errorreject_mutation_error when applicablepersistence_error when applicableFor Acceptance Targets, specify exact targets such as:
For Implementation Path, say explicitly whether the current code path is preserved or intentionally redesigned.
Check these questions before closing the work:
App.tsx?Avoid these patterns:
App.tsx with panel-specific interaction logic