@leejungkiin/awkit 1.3.7 → 1.4.0

package/templates/CODEBASE.md

@@ -1,14 +1,15 @@
 # {{PROJECT_NAME}} — Codebase Map
 
-> **Project Type:** {{PROJECT_TYPE}} | **Stage:** {{PROJECT_STAGE}}
-> **Tech Stack:** {{TECH_STACK_SUMMARY}}
+> **Project Type:** {{PROJECT_TYPE}} | **Tech Stack:** {{TECH_STACK_SUMMARY}}
 > **Last Synced:** {{DATE}}
 
----
+> [!NOTE]
+> AI PHẢI đọc file này TRƯỚC KHI dùng `grep_search` / `codebase_search` / `list_dir`.
+> Đọc → xác định target → search cụ thể. KHÔNG search "mù".
 
-## 🗺️ Layer Map
+---
 
-> _AI: Dùng bản đồ này để định vị file trước khi scan directory_
+## 🗺️ Directory Structure
 
 ```
 {{DIR_STRUCTURE}}
@@ -16,47 +17,32 @@
 
 ---
 
-## 📁 Feature Areas
-
-| Area | Location | Description |
-|------|----------|-------------|
-| _(example)_ Features | `{{FEATURES_DIR}}` | Main feature modules |
-| _(example)_ Shared UI | `{{SHARED_UI_DIR}}` | Reusable UI components |
-| _(example)_ Services | `{{SERVICES_DIR}}` | Business logic & data layer |
-| _(example)_ Models | `{{MODELS_DIR}}` | Data models & DTOs |
-
-> ⚠️ Update this table after adding new feature areas.
-
----
+## 📁 File Index
 
-## 🔥 Firebase Integration
+> Compact format: `path` → purpose (1 line mỗi file)
 
-| Feature | Status | Notes |
-|---------|--------|-------|
-| Analytics | ✅ | Event tracking |
-| Crashlytics | ✅ | Crash reporting |
-| Remote Config | ✅ | Feature flags |
-| Auth | ✅ | Sign in methods |
-| Firestore | ⬜ | — |
-| Storage | ⬜ | — |
+### Core / Infrastructure
 
----
+| Path | Purpose |
+|------|---------|
+| `{{CORE_FILE_1}}` | {{PURPOSE_1}} |
+| `{{CORE_FILE_2}}` | {{PURPOSE_2}} |
 
-## 🏗️ Architecture
+### Features
 
-- **Pattern:** {{ARCHITECTURE}}
-- **State Management:** {{STATE_MANAGEMENT}}
-- **Networking:** {{NETWORKING}}
-- **Storage:** {{STORAGE}}
+| Path | Purpose |
+|------|---------|
+| `{{FEATURE_FILE_1}}` | {{PURPOSE_1}} |
+| `{{FEATURE_FILE_2}}` | {{PURPOSE_2}} |
 
----
+### UI / Views
 
-## 📏 Naming Conventions
+| Path | Purpose |
+|------|---------|
+| `{{VIEW_FILE_1}}` | {{PURPOSE_1}} |
+| `{{VIEW_FILE_2}}` | {{PURPOSE_2}} |
 
-- **Files:** `PascalCase` (Swift/Kotlin) or `kebab-case` (JS/TS)
-- **Functions/Methods:** `camelCase`
-- **Constants:** `UPPER_SNAKE_CASE`
-- **Variables:** `camelCase`
+> ⚠️ Thêm file mới vào section phù hợp. Dùng `/codebase-sync` để auto-update.
 
 ---
 
@@ -67,14 +53,12 @@
 | `.project-identity` | AI project context |
 | `CODEBASE.md` | This file — codebase map for AI |
 
-> Add important files here as the project grows.
-
 ---
 
 ## 📝 Notes
 
-_Add architecture decisions, gotchas, and important context here._
+_Architecture decisions, gotchas, và context quan trọng._
 
 ---
 
-*Auto-generated by `awkit init` — keep this file updated with `/codebase-sync`*
+*Auto-generated by `awkit init` — keep updated with `/codebase-sync`*

package/templates/configs/trello-config.json

@@ -1,5 +1,5 @@
 {
   "BOARD_NAME": "Appdexter - Code Magic",
-  "LIST_NAME": "Your Backlog List",
-  "CARD_NAME": "Project Card Name or ID"
+  "LIST_NAME": "Kiên",
+  "CARD_NAME": "FitWitness Android"
 }

package/templates/project-identity/android.json

@@ -1,5 +1,10 @@
 {
+  "_comments": {
+    "projectId": "Auto-generated from folder name. DO NOT change — used by Symphony for task scoping.",
+    "trello": "Fill in your Trello board/list/card names. Run 'awkit trello info' to verify."
+  },
   "projectName": "MyAndroidApp",
+  "projectId": "myandroidapp",
   "projectType": "android",
   "packageName": "com.company.myandroidapp",
   "primaryLanguage": "en",
@@ -16,6 +21,11 @@
     "testing": "JUnit + Espresso",
     "buildSystem": "Gradle (KTS)"
   },
+  "trello": {
+    "board": "Your Board Name",
+    "list": "Your List Name",
+    "card": "Your Card Name"
+  },
   "projectStage": "planning",
   "codingStandards": {
     "language": "en",

package/templates/project-identity/backend-nestjs.json

@@ -1,5 +1,10 @@
 {
+  "_comments": {
+    "projectId": "Auto-generated from folder name. DO NOT change — used by Symphony for task scoping.",
+    "trello": "Fill in your Trello board/list/card names. Run 'awkit trello info' to verify."
+  },
   "projectName": "MyBackendAPI",
+  "projectId": "mybackendapi",
   "projectType": "backend",
   "primaryLanguage": "en",
   "techStack": {
@@ -12,6 +17,11 @@
     "testing": "Jest",
     "deployment": "Docker + Cloud Run"
   },
+  "trello": {
+    "board": "Your Board Name",
+    "list": "Your List Name",
+    "card": "Your Card Name"
+  },
   "projectStage": "planning",
   "codingStandards": {
     "language": "en",

package/templates/project-identity/expo.json

@@ -1,5 +1,10 @@
 {
+  "_comments": {
+    "projectId": "Auto-generated from folder name. DO NOT change — used by Symphony for task scoping.",
+    "trello": "Fill in your Trello board/list/card names. Run 'awkit trello info' to verify."
+  },
   "projectName": "MyExpoApp",
+  "projectId": "myexpoapp",
   "projectType": "expo",
   "bundleIdentifier": "com.company.myexpoapp",
   "primaryLanguage": "en",
@@ -15,6 +20,11 @@
     "testing": "Jest + Detox",
     "build": "EAS Build"
   },
+  "trello": {
+    "board": "Your Board Name",
+    "list": "Your List Name",
+    "card": "Your Card Name"
+  },
   "projectStage": "planning",
   "codingStandards": {
     "language": "en",

package/templates/project-identity/ios.json

@@ -1,5 +1,10 @@
 {
+  "_comments": {
+    "projectId": "Auto-generated from folder name. DO NOT change — used by Symphony for task scoping.",
+    "trello": "Fill in your Trello board/list/card names. Run 'awkit trello info' to verify."
+  },
   "projectName": "MyiOSApp",
+  "projectId": "myiosapp",
   "projectType": "ios",
   "bundleIdentifier": "com.company.myiosapp",
   "primaryLanguage": "en",
@@ -15,6 +20,11 @@
     "testing": "XCTest",
     "packageManager": "SPM"
   },
+  "trello": {
+    "board": "Your Board Name",
+    "list": "Your List Name",
+    "card": "Your Card Name"
+  },
   "projectStage": "planning",
   "codingStandards": {
     "language": "en",

package/templates/project-identity/web-nextjs.json

@@ -1,5 +1,10 @@
 {
+  "_comments": {
+    "projectId": "Auto-generated from folder name. DO NOT change — used by Symphony for task scoping.",
+    "trello": "Fill in your Trello board/list/card names. Run 'awkit trello info' to verify."
+  },
   "projectName": "MyWebApp",
+  "projectId": "mywebapp",
   "projectType": "react_web",
   "primaryLanguage": "en",
   "techStack": {
@@ -12,6 +17,11 @@
     "auth": "NextAuth.js",
     "deployment": "Vercel"
   },
+  "trello": {
+    "board": "Your Board Name",
+    "list": "Your List Name",
+    "card": "Your Card Name"
+  },
   "projectStage": "planning",
   "codingStandards": {
     "language": "en",

package/templates/workflow_dual_mode_template.md

@@ -34,7 +34,7 @@ description: [Short description of the workflow]
 ### Phase 1: Context & Setup
 1. **Understand Intent:**
    - "Bạn muốn làm gì với [Command]?"
-   - (AI analyzes context from `.project-identity` & `.symphony`)
+   - (AI analyzes context from `.project-identity` & `.beads`)
 
 2. **Configuration:**
    - [Question 1]
@@ -68,7 +68,7 @@ description: [Short description of the workflow]
    - Locations of artifacts.
 
 2. **Memory Sync:**
-   - Auto-sync with Symphony (Task) & Brain (Knowledge).
+   - Auto-sync with Beads (Task) & Brain (Knowledge).
 
 3. **Next Steps Menu:**
    ```markdown
@@ -79,9 +79,9 @@ description: [Short description of the workflow]
 
 ---
 
-## 🧠 Brain & Symphony Integration
+## 🧠 Brain & Beads Integration
 
-- **Input:** Check `symphony_available_tasks(filter="my")` to resume context.
+- **Input:** Check `bd list --status in_progress` to resume context.
 - **Output:**
-  - Create/Update Symphony task.
+  - Create/Update Beads task.
   - Create Brain memory file if knowledge is valuable.

package/workflows/_uncategorized/conductor-codex.md

@@ -0,0 +1,125 @@
+---
+description: 🔍 Codex Conductor — Gọi Codex CLI rà soát code, debug, review logic, và verify refactor
+---
+
+# /conductor-codex — Three-Agent Inspector Workflow
+
+> Antigravity gọi Codex CLI (headless, read-only) khi cần rà soát chuyên sâu.
+> Codex CHỈ ĐỌC + TẠO BÁO CÁO `.md`. KHÔNG BAO GIỜ sửa code.
+
+// turbo-all
+
+---
+
+## Prerequisites
+
+1. Kiểm tra Codex CLI:
+```bash
+which codex || echo "NOT_INSTALLED"
+```
+2. Nếu chưa cài → đề xuất cài:
+```bash
+npm i -g @openai/codex
+```
+3. Tạo thư mục report nếu chưa có:
+```bash
+mkdir -p codex-reports
+```
+
+---
+
+## Sub-commands
+
+### `/conductor-codex:debug` — Phân tích root cause bug
+
+1. User mô tả bug (crash, lỗi logic, unexpected behavior)
+2. Thông báo: "🔍 Đang gọi Codex CLI phân tích bug..."
+3. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 120 codex "A bug was reported: <BUG_DESCRIPTION>. Analyze the codebase to find the root cause. List: (1) most likely root cause with file:line, (2) contributing factors, (3) suggested fix approach. DO NOT edit any files." --approval-mode suggest -q 2>/dev/null
+```
+4. Parse output → lưu vào `codex-reports/bug-analysis-<DATE>.md`
+5. Tóm tắt findings cho user
+6. Nếu critical → Antigravity thực hiện fix
+
+### `/conductor-codex:review` — Pre-commit code review
+
+1. Kiểm tra có uncommitted changes: `git diff --stat`
+2. Thông báo: "🔍 Đang gọi Codex CLI review code..."
+3. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 120 codex "Review the uncommitted changes in this repo. Check for: bugs, logic errors, edge cases, thread safety, security issues, performance problems. Rank issues by severity (critical/warning/info). DO NOT edit any files." --approval-mode suggest -q 2>/dev/null
+```
+4. Parse output → lưu vào `codex-reports/review-<DATE>.md`
+5. Tóm tắt: issues found + severity
+6. Nếu clean → suggest `git commit`
+
+### `/conductor-codex:logic` — Phân tích logic & edge cases
+
+1. Xác định file/module cần kiểm tra
+2. Thông báo: "🔍 Đang gọi Codex CLI kiểm tra logic..."
+3. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 120 codex "Analyze <FILE_OR_MODULE> for logic correctness. Focus on: edge cases (null, empty, boundary), race conditions, error handling gaps, unreachable code, off-by-one errors. List each issue with file:line and severity. DO NOT edit any files." --approval-mode suggest -q 2>/dev/null
+```
+4. Parse output → lưu vào `codex-reports/logic-analysis-<DATE>.md`
+5. Tóm tắt findings cho user
+
+### `/conductor-codex:test` — Generate test cases
+
+1. Xác định feature/module cần test
+2. Thông báo: "🔍 Đang gọi Codex CLI generate test cases..."
+3. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 120 codex "Analyze <FILE_OR_MODULE> and generate a comprehensive list of test cases. Include: happy path, edge cases, error cases, boundary values. Format as markdown table with columns: Test Name | Input | Expected Output | Type. DO NOT edit any files." --approval-mode suggest -q 2>/dev/null
+```
+4. Parse output → lưu vào `codex-reports/test-cases-<DATE>.md`
+5. Trình bày test plan cho user
+
+### `/conductor-codex:plan-review` — Review implementation plan
+
+1. Đọc `implementation_plan.md` hiện tại
+2. Thông báo: "🔍 Đang gọi Codex CLI review plan..."
+3. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 120 codex "Review this implementation plan in the current directory. Find: logic holes, missing error handling, security risks, race conditions, scalability issues, missing edge cases. Rate each issue by severity (critical/warning/info). DO NOT edit any files." --approval-mode suggest -q 2>/dev/null
+```
+4. Parse output → lưu vào `codex-reports/plan-review-<DATE>.md`
+5. Tóm tắt issues → Antigravity cập nhật plan
+
+---
+
+## Fallback Rules
+
+```yaml
+cli_not_installed:
+  - "⚠️ Codex CLI chưa cài. Chạy: npm i -g @openai/codex"
+  - Offer to install automatically
+
+cli_unavailable:
+  - "⚠️ Codex CLI không khả dụng, tiếp tục với Antigravity-only"
+  - Do NOT block workflow
+
+cli_timeout:
+  - "⏳ Codex phân tích quá lâu (>120s), bỏ qua và tiếp tục"
+
+cli_error:
+  - Log error
+  - Fall back gracefully
+  - Suggest: "codex --version" to check installation
+```
+
+---
+
+## Communication
+
+Mỗi khi gọi CLI, LUÔN thông báo user:
+```
+🔍 Đang gọi Codex CLI để [mục đích]...
+```
+
+Sau khi nhận kết quả:
+```
+✅ Codex rà soát xong. Báo cáo: codex-reports/<file>.md
+📊 Tóm tắt: [key findings]
+```

package/workflows/_uncategorized/conductor.md

@@ -0,0 +1,97 @@
+---
+description: 🎼 CLI Conductor — Gọi Gemini CLI phân tích, lên chiến lược, và review code project-wide
+---
+
+# /conductor — Two-Agent Orchestration Workflow
+
+> Antigravity chủ động gọi Gemini CLI (headless) khi cần tầm nhìn toàn project.
+> CLI chạy quota pool riêng → nhân đôi AI capacity.
+
+// turbo-all
+
+---
+
+## Sub-commands
+
+### `/conductor:analyze` — Phân tích project-wide
+
+1. Xác định project root (dùng `.project-identity` hoặc `CODEBASE.md`)
+2. Thông báo user: "📡 Đang gọi Gemini CLI phân tích cấu trúc project..."
+3. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 60 gemini -p "Analyze the project structure. List main modules, their responsibilities, key files, and dependencies. Be concise." --approval-mode plan 2>/dev/null
+```
+4. Parse output → tóm tắt cho user
+5. Nếu project có `conductor/tracks.md` → cập nhật
+6. Nếu chưa có `conductor/` → hỏi user có muốn tạo không
+
+### `/conductor:track` — Tạo/cập nhật strategic track
+
+1. Đọc `conductor/tracks.md` hiện tại (nếu có)
+2. User mô tả mục tiêu chiến lược
+3. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 60 gemini -p "Given this project context and goal: <GOAL>. Create a strategic track with: objectives, key milestones, and task breakdown. Current tracks: <EXISTING_TRACKS>" --approval-mode plan 2>/dev/null
+```
+4. Parse output → ghi vào `conductor/tracks.md`
+5. Tạo Symphony tasks từ task breakdown (nếu user đồng ý)
+
+### `/conductor:delegate` — Delegate task cho CLI xử lý
+
+1. Xác định task cần CLI (phân tích, review, generate)
+2. Build prompt với context đầy đủ
+3. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 60 gemini -p "<TASK_PROMPT>" --approval-mode plan 2>/dev/null
+```
+4. Nhận kết quả → tích hợp vào workflow hiện tại
+5. Tiếp tục code/debug với insights từ CLI
+
+### `/conductor:review` — Pre-commit review qua CLI
+
+1. Lấy diff: `git diff --staged` hoặc `git diff`
+2. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 60 gemini -p "Review these code changes for bugs, security issues, and best practices: $(git diff --staged --stat)" --approval-mode plan 2>/dev/null
+```
+3. Parse output → báo cáo issues cho user
+4. Nếu clean → suggest `git commit`
+
+### `/conductor:setup` — Khởi tạo conductor infrastructure
+
+1. Tạo thư mục `conductor/` tại project root
+2. Copy template `conductor-tracks.md` → `conductor/tracks.md`
+3. Thêm `conductor/` vào `.gitignore` (nếu user muốn)
+4. Thông báo: "✅ Conductor infrastructure ready!"
+
+---
+
+## Fallback Rules
+
+```yaml
+cli_unavailable:
+  - "⚠️ Gemini CLI không khả dụng, tiếp tục với Antigravity-only mode"
+  - Do NOT block workflow
+
+cli_timeout:
+  - "⏳ CLI phân tích quá lâu (>60s), bỏ qua và tiếp tục"
+
+cli_error:
+  - Log error
+  - Fall back gracefully
+  - Suggest: "gemini --version" to check installation
+```
+
+---
+
+## Communication
+
+Mỗi khi gọi CLI, LUÔN thông báo user:
+```
+📡 Đang gọi Gemini CLI để [mục đích]...
+```
+
+Sau khi nhận kết quả:
+```
+✅ CLI phân tích xong. Tóm tắt: [key findings]
+```

package/workflows/_uncategorized/trello-sync.md

@@ -0,0 +1,52 @@
+---
+description: 🔄 Đồng bộ thủ công Project Status lên Trello Card (tuân thủ quy tắc Anti-Spam)
+---
+
+# 🔄 Trello Sync Workflow (`/trello-sync`)
+
+Quy trình này hướng dẫn AI đồng bộ thủ công mức độ hoàn thành của dự án hiện tại lên Trello Card, dựa trên dữ liệu từ thiết kế, Kiro Specs, hoặc Symphony tasks.
+
+## 🎯 Mục đích
+Được sử dụng khi người dùng muốn ép (force) AI cập nhật tiến độ tổng thể lên Trello, hoặc khi AI cần tổng kết (summarize) status sau một Sprint/Milestone quan trọng.
+
+## 📋 Hướng dẫn thực thi
+
+### Bước 1: Thu thập ngữ cảnh hiện tại
+1. Kiểm tra trạng thái dự án hiện tại (đọc `Symphony` tasks, `.kiro/specs/tasks.md` hoặc các file spec nội bộ).
+2. Tóm tắt lại các **module hoặc tính năng lớn** (High-level features) đã hoàn thành, đang làm, và chưa làm.
+
+### Bước 2: Load Trello Configuration
+1. Đảm bảo shell đã có sẵn `TRELLO_KEY` và `TRELLO_TOKEN` (từ biến môi trường máy). CLI đã tự động thừa hưởng.
+2. Đọc file `.trello-config.json` tại thư mục gốc của dự án để lấy thông tin `<board>`, `<list>`, và `<card>`.
+3. Nếu file cấu hình không tồn tại, báo lỗi và yêu cầu user tạo cấu hình hoặc chạy `/init`.
+
+### Bước 3: Cập nhật Trello (Cân bằng giữa Chi tiết và Tối giản)
+> **⛔ CẢNH BÁO QUAN TRỌNG:**
+> Đừng "spam" tạo checklist item cho các task code le te. Nhưng cũng ĐỪNG quá trống rỗng. Hãy cập nhật Card Description và Comment đầy đủ ý nghĩa cho Quản lý dự án.
+
+1. Hãy sử dụng thư viện native CLI `awkit trello`. Không dùng lệnh `trello-cli` thuần hay script Python/Bash.
+2. **Cập nhật Mô tả (Description)** tổng quan của dự án (cực kỳ quan trọng để Quản lý nắm bắt):
+   ```bash
+   awkit trello desc "**Tech Stack:** Kotlin, Compose... **Hiện trạng:** Đang làm module Foundation..."
+   ```
+3. CHỈ đồng bộ tên Milestone / Module / Feature lớn vào Checklist Item.
+4. **Thêm Checklist mới** (nếu module đó chưa có checklist riêng):
+   ```bash
+   awkit trello checklist "<Milestone / Module Name>"
+   ```
+5. **Thêm item mới vào Checklist** (Task mới):
+   ```bash
+   awkit trello item "<Feature Name>"
+   ```
+6. **Mark done một item** (Module lớn đã xong):
+   ```bash
+   awkit trello complete "<Feature Name>"
+   ```
+7. **Thêm Comment** tổng kết milestone:
+   ```bash
+   awkit trello comment "🎯 Milestone Update: Chúng ta đã hoàn thành feature..."
+   ```
+
+### Bước 4: Hoàn tất
+1. Tóm tắt lại với user về các module/tính năng đã được sync thành công lên Trello card.
+2. Gợi ý Next step: Gọi `/next` hoặc `/code` để tiếp tục làm việc.

package/workflows/quality/visual-debug.md

@@ -5,30 +5,84 @@ safe_auto_run: false
 
 # Visual Debug Workflow
 
-Turn a screenshot into a code fix.
+Turn a screenshot into actionable UI improvements — both technical bugs AND design quality issues.
+
+> **Mindset**: You are a Senior UI/UX Designer doing a heuristic review, NOT just a developer looking for crashes. Every screen must meet premium app standards.
+
+## 1. Visual Analysis (Dual-Lens)
 
-## 1. Visual Analysis
 **Trigger**: User uploads a screenshot.
 
-1. **Analyze Image**:
-   - Identify the screen/feature.
-   - Spot the anomaly (Error message, misalignment, wrong color, broken layout).
-   - *Self-Question*: "What looks wrong in this picture compared to a premium app?"
+### Lens A — Technical Bug Scan
+1. **Identify Screen**: Name the screen/feature shown.
+2. **Spot Technical Anomalies**:
+   - Broken layout, text overflow, clipped content
+   - Wrong colors, missing assets, placeholder data still visible
+   - Error messages, loading spinners stuck, empty states missing
+
+### Lens B — UI/UX Designer Review (CRITICAL)
+Run through these **7 checkpoints** on EVERY image. For each checkpoint, produce a finding or explicitly say "OK".
+
+| # | Checkpoint | What to look for |
+|---|-----------|-----------------|
+| 1 | **Information Completeness** | Are all required data fields present? Missing inputs that the feature logically needs? (e.g., a "Add Medicine" form without dosage field) |
+| 2 | **Naming & Copy Consistency** | Do button labels, titles, and section headers match the screen's purpose? Any contradictions? (e.g., screen title says "Add X" but button says "Save Y") |
+| 3 | **Visual Hierarchy** | Is it clear what's most important? Do headings, font sizes, and colors guide the eye correctly? |
+| 4 | **Spacing & Layout Balance** | Large empty gaps? Content crammed? Proper padding and margins? Consistent spacing rhythm? |
+| 5 | **Component State Clarity** | Can the user tell which items are selected, disabled, required, or interactive? Are disabled buttons explained? |
+| 6 | **Navigation Consistency** | Does the tab bar / nav bar state match the current screen? Are back buttons and breadcrumbs correct? |
+| 7 | **Interaction Completeness** | Are there enough options in selection groups? Missing common choices? Proper validation hints for required fields? |
+
+### Output Format
+```
+## Visual Analysis Report
+
+### 🐛 Technical Issues
+- [list or "None found"]
+
+### 🎨 Design Issues
+| # | Checkpoint | Status | Finding |
+|---|-----------|--------|---------|
+| 1 | Info Completeness | ⚠️ | Missing dosage input field |
+| 2 | Naming Consistency | ⚠️ | Button "Save X" contradicts title "Add Y" |
+| 3 | Visual Hierarchy | ✅ | OK |
+| ... | ... | ... | ... |
+
+### 📋 Priority Actions
+1. [Critical] ...
+2. [Important] ...
+3. [Nice-to-have] ...
+```
 
 ## 2. Code Mapping
-1. **Locate Component**: based on text or visual structure, find the source file (e.g., `ProfileView.swift` or `home_screen.xml`).
-2. **Verify Context**: Read the file to understand the current state implementation.
+1. **Locate Component**: Based on text, screen title, or visual structure, find the source file.
+2. **Verify Context**: Read the file to understand the current implementation.
+3. **Cross-Reference Design Spec**: If a design doc or spec exists (`.kiro/specs/`, `docs/specs/`), compare the implementation against it.
 
 ## 3. Diagnosis
-1. **Hypothesize**: Why is it rendering this way?
+
+### For Technical Bugs
+1. **Hypothesize** root cause:
    - *Logic Error*: State variable is wrong?
    - *Style Error*: Padding/Margin/Flex issue?
    - *Data Error*: Null or undefined data?
 2. **Confirm**: Correlate code logic with the visual bug.
 
+### For Design Issues
+1. **Classify Severity**:
+   - 🔴 **Critical**: Missing data/functionality that blocks user goals (e.g., no dosage field in medicine form)
+   - 🟡 **Important**: UX friction or inconsistency that confuses users (e.g., mismatched button label)
+   - 🟢 **Nice-to-have**: Polish and refinement (e.g., better spacing, shadow depth)
+2. **Propose Design Fix**: Describe the ideal state with specific UI recommendations.
+
 ## 4. Remediation
-1. **Propose Fix**: Explain the plan to the user.
-2. **Apply Fix**: Edit the code.
+1. **Present Report**: Show the analysis table with all findings to the user.
+2. **Prioritize**: Ask user which issues to fix now vs. later.
+3. **Apply Fixes**: Edit code for approved items.
+   - Technical bugs → direct code fix
+   - Design issues → may require new UI components, layout changes, or copy updates
 
 ## 5. Verification
-1. Ask user to rebuild or preview to confirm the visual glitch is gone.
+1. Ask user to rebuild or preview.
+2. Re-run the 7 checkpoints on the updated screenshot if provided.
+3. Confirm all critical and important issues are resolved.