| name | ui-ai-first |
| description | Final audit of a large task before closure — finds which operations
are available only via code / curl / SQL and decides per each:
automate with a skill or AI agent (A) or create a UI task (B).
Protects against invisible usability debt.
Walks through each implemented block: reads task.md + reports +
guides + code → forms a sub-table with operations → A/B
classification → master table + phased roadmap. Does not implement
findings — records them as roadmap items.
Use when: final step of an arch-first task before closure; review
of a closed large task; "/ui-ai-first", "usability audit",
"what's still only via code"
|
UI/AI-First Protocol
Final protocol of the *-first family. Launched after implementing a large task — before formal closure. Protects against invisible usability debt: features implemented in code but unavailable to a non-developer (everything via curl / SQL / Claude Code).
Input
A completed arch-first task near closure; its task.md, block reports, guides, and code changes.
Output
ui-ai-first-report.md with operations classified A (automate via skill / AI agent) or B (build UI), and a phased roadmap of B items.
Hands off to
ship-first (called from ship-first Step 0.6 when run_ui_ai_first=true).
Introduction
Why it's needed
Every large task leaves "code-only" operations. In reports this doesn't sound like a problem — "feature works", "endpoint in prod". But when an operator wants to use the capability — they hit curl with admin_password in JSON or SQL INSERT into several tables.
3 months later these capabilities effectively exist only on paper — no one but the task author uses them. This is technical debt that looks like "everything's ready".
A/B classification principle
For each "code-only" operation — one of two:
- A — skill / AI agent for rare or technical operations. Quick to build, cheap to run
- B — UI task for frequent operator operations where a skill is insufficient — need a form, button, dashboard
Not every feature needs UI. Not every operation needs a skill.
What it does NOT do
Does not implement findings. Only classifies and forms a prioritized roadmap. Implementation — separate work streams with their own library-first / plan-first.
Step 1 — Get task_path
If passed as argument — use. If not — ask user or propose the last closed task from routing DB.
Verify task is actually closed:
- task.md has blocks with ✅
- ≥1-2
report-NN.md in task log
If not — stop: "Task is not yet closed. Audit is premature."
Step 2 — Gather list of implemented blocks
Read task.md → all blocks with ✅ or "Done" mark. Ignore planned or cancelled.
For each block record: number/name, report-NN.md, related guides, commits.
Step 3 — Propose sub-table structure for approval
Rule: 1 task block = 1 sub-table.
Exception: if a block has significant sub-blocks with many separate operations — extract them as separate Sub-tables. Don't merge — focus is lost.
Show user numbered list of S1 → Sn with expected volume. Mark hot zones with ⭐. Wait for approval.
Step 4 — Pin structure in the master file
Create {log_dir}/ui-ai-first-master.md with skeleton:
# UI/AI-First Audit — {task_slug}
**Start date:** YYYY-MM-DD
## Structure
[approved sub-table list]
## Sub-tables
See: ui-ai-first-b1.md, ui-ai-first-b2.md, ...
## Master table
[placeholder — Step 6]
## Roadmap
[placeholder — Step 7]
## Summary
[placeholder — Step 8]
This is the index and final aggregation.
Step 5 — For each block: build sub-table (iteratively)
Cycle: S1 → Sn. Per S:
- Read sources:
report-NN.md, guides, key code files
- Form sub-table per template:
## Sub-table S{N} — Block {X} ({name})
**Sources:** {list}
**What the block brought:** {1-3 sentences}
### Operation groups
| # | Operation | Currently how | Frequency | Decision (A/B/–) | Skill/task |
|---|-----------|---------------|-----------|-------------------|------------|
| 1 | ... | ... | ... | A | /skill-name — description |
| 2 | ... | ... | ... | B | UI task — description |
### Result S{N}
- UI tasks: {N}
- Skills: {M}
- Main takeaway: {1-3 sentences}
- Show user → approve → write to
ui-ai-first-b{N}.md
- Next block
Frequency categories
| Level | When |
|---|
| High | Daily / several times per week |
| Medium | Weekly / monthly |
| Low | Quarterly, ad-hoc, debugging |
| Very low | One-off, GDPR / incident-only |
Decisions
| Code | When |
|---|
| A | Rare/technical — skill/agent faster to build |
| B | Frequent operator — needs UI |
| A + B | Skill as stopgap, UI mid-term as stable solution |
| – | Neither needed — explain why |
Step 6 — Master table
Merge all operations. Sort by priority:
- High ⭐ — frequent operator ops without A/B + critical blockers + HIGH bugs
- Medium — frequent ops with A + medium-frequency ops
- Low — rare, maintenance, optional
- Architectural TODO — cross-cutting system improvements
Format:
## Master table
### High priority ⭐
| # | Operation | Sub-table | Decision | Skill/task |
### Medium priority
[same shape]
### Low priority (backlog)
[same]
### Architectural TODO
| TODO | Referenced in |
Show user → approve → append to master.
Step 7 — Phased roadmap
Group master table into 6 stages:
| Stage | What | When |
|---|
| 0 — Prerequisites | Blockers — without them next stages don't work | Immediately after task closure |
| 1 — Burning pain points | 3-5 high-priority skills + HIGH bugs | After Stage 0 |
| 2 — Basic automation | Medium A skills for routine ops | After Stage 1 |
| 3 — UI tasks (mid-term) | Main B tasks | After Stage 2 |
| 4 — GDPR + long-tail maintenance | Compliance + rare ops | As client base grows |
| 5 — Backlog | Low-priority A skills + long-term UI | When there's time |
| 6 — Architectural TODO | System improvements (lifecycle, audit-log, signed URLs) | Separate streams |
For each Stage — short list of concrete items (skill names + descriptions / UI task names).
Step 8 — Summary by category
## Summary
| Category | Count |
|---|---|
| Skills Stage 1 (burning) | ... |
| Skills Stage 2 (basic automation) | ... |
| UI tasks Stage 3 | ... |
| GDPR + maintenance Stage 4 | ... |
| Backlog Stage 5 | ... |
| Architectural TODO Stage 6 | ... |
| **Total skills** | ~N |
| **Total UI tasks** | M |
**Main takeaways:**
- {where the main pain is}
- {what to do first}
- {which risks if not doing}
---
**Audit finished YYYY-MM-DD.**
Step 9 — Optional: create backlog items
Ask: "Create separate files in tasks/backlog/ for each roadmap item? (1=yes / 2=no)"
If 2 (no): roadmap stays only in master file. Done.
If 1 (yes): for each item create tasks/backlog/{type}--{slug}.md:
---
type: backlog
created: YYYY-MM-DD
source: ui-ai-first audit of task {task_slug}
priority: high|medium|low
category: skill|ui|architecture
stage: 0-6
---
# {Item name}
**What:** {description}
**Why:** {rationale from audit}
**Source:** see master file — Stage {N}
**Next step:** library-first → plan-first → code (separate pass)
Anti-patterns
❌ Audit only by guides
Guides cover user-facing aspects. Technical operations (SQL migrations, ad-hoc scripts) are often not mentioned. Without reading reports and code — operations will be missed.
Rule: for each block mandatory read report-NN.md + key code files.
❌ Classify everything as B (UI)
UI is slow and expensive. Most rare/technical operations should be A — much faster and cheaper.
Rule: B only when operation is frequent operator — otherwise A.
❌ Classify everything as A (skill)
Frequent operator operations must be in UI — otherwise the operator is stuck on CLI and Claude Code.
Rule: if the operation runs daily or several times per week — it's B.
❌ Not extracting sub-blocks as separate S
Hot zones get lost in parent block's sub-table. Gives false signal "parent is routine" while sub-block is the hottest part.
Rule: if a block has a sub-block with many separate operations — extract as separate S.
❌ Implement findings immediately
ui-ai-first is audit, not implementation. If mid-audit you want to write a skill — stop. Breaks focus, triples audit length.
Rule: all findings → roadmap items. Implementation — separate streams.
❌ Create backlog items automatically
Step 9 is optional. Not every user wants to split a roadmap into 25 files. Ask, don't do by default.
File structure
{log_dir}/
├── ui-ai-first-master.md # structure + master + roadmap + summary
├── ui-ai-first-b1.md # sub-table S1
├── ui-ai-first-b2.md
└── ui-ai-first-b{N}.md
One protocol = one file per iteration.
Launch triggers
- Direct:
/ui-ai-first <task_path> or /ui-ai-first without arguments
- From
arch-first — automatically as final block of a large task (5+ blocks)
- From
ship-first — automatically as Step 0.5 before formal closure
When NOT to launch
- Task is not yet closed (no blocks with ✅)
- Small task (1-2 blocks) — audit is more expensive than findings
- Purely refactoring task without new endpoints / tables / operations — nothing to audit
Related skills
- arch-first — decomposes and drives large multi-block tasks; may invoke ui-ai-first as final block
- ship-first — invokes ui-ai-first at Step 0.5 before formal task closure
- library-first — parallel protocol, but for planning code reuse before implementation
- flow-first — parallel protocol, for landscape alignment before library-first
Step 99 — Log invocation
sqlite3 {routing_db} \
"INSERT INTO skill_invocations (task_id, block_num, skill_name, invoked_at)
VALUES ('{slug}', '{N}', 'ui-ai-first', datetime('now'))" 2>/dev/null || true
If {slug} / {N} unknown → hook writes empty; || true guards failure.
