@orderful/droid 0.25.2 → 0.27.0

package/src/tools/tech-design/skills/tech-design/references/gaps.md

@@ -0,0 +1,328 @@
+# Gap Analysis
+
+**Trigger:** `/tech-design gaps` or user asks "what's missing?"
+
+**Goal:** Show checklist of sections that are empty or missing. Offer `/think` for each.
+
+## Procedure
+
+### 1. Read Thought Doc
+
+```bash
+thought_doc=$(cat "$thought_doc_path")
+
+# Parse sections (lines starting with ##)
+sections=$(grep "^## " "$thought_doc_path" | sed 's/^## //')
+```
+
+### 2. Define Expected Sections
+
+**Core sections** (always check):
+
+- Background
+- Proposal
+- Open Questions
+
+**Common sections** (check if relevant):
+
+- Scope / Non-goals
+- Data Model
+- API Surface
+- Implementation Plan
+- Key Decisions
+- Trade-off Analysis
+- Risks & Mitigations
+- Metrics
+- Rollout Plan
+- Security Considerations
+
+### 3. Identify Gaps
+
+**A section is "empty" if:**
+
+- It exists as a header but has no content
+- Content is just placeholders like `{Why we're doing this}`
+- Content is < 50 characters (likely just template)
+
+**A section is "missing" if:**
+
+- Not present in thought doc at all
+- Likely needed based on PRD/project type
+
+```bash
+# For each expected section:
+if ! section_exists; then
+  missing+=("$section")
+elif section_is_empty; then
+  empty+=("$section")
+else
+  complete+=("$section")
+fi
+```
+
+### 4. Determine Importance
+
+**Critical** (should have before publishing):
+
+- Background
+- Proposal
+- Risks & Mitigations
+- Rollout Plan (for user-facing features)
+- Security Considerations (if handling user input or sensitive data)
+
+**Important** (nice to have):
+
+- Scope / Non-goals
+- Data Model (if schema changes)
+- API Surface (if new endpoints)
+- Implementation Plan
+- Key Decisions
+
+**Optional** (can skip or keep light):
+
+- Metrics (can be in thought doc only)
+- Trade-off Analysis (can be implicit in Decisions)
+
+### 5. Infer from Project Context
+
+**Check PRD for clues:**
+
+```bash
+# If PRD mentions "API", mark API Surface as important
+grep -i "API\|endpoint\|REST" "$prd_path" && api_needed=true
+
+# If PRD mentions "database", mark Data Model as important
+grep -i "database\|schema\|table\|entity" "$prd_path" && data_model_needed=true
+
+# If PRD mentions "security\|auth\|permission", mark Security as critical
+grep -i "security\|auth\|permission\|sensitive" "$prd_path" && security_critical=true
+
+# If user-facing, rollout is critical
+grep -i "user\|customer\|partner" "$prd_path" && rollout_critical=true
+```
+
+### 6. Output Checklist
+
+```bash
+echo "📋 Tech Design Gaps Analysis"
+echo ""
+
+if [ ${#complete[@]} -gt 0 ]; then
+  echo "✓ Complete:"
+  for section in "${complete[@]}"; do
+    echo "  • $section"
+  done
+  echo ""
+fi
+
+if [ ${#empty[@]} -gt 0 ]; then
+  echo "⚠️  Started but empty:"
+  for section in "${empty[@]}"; do
+    criticality=$(get_criticality "$section")
+    echo "  • $section [$criticality]"
+  done
+  echo ""
+fi
+
+if [ ${#missing[@]} -gt 0 ]; then
+  echo "❌ Missing:"
+  for section in "${missing[@]}"; do
+    criticality=$(get_criticality "$section")
+    echo "  • $section [$criticality]"
+  done
+  echo ""
+fi
+
+echo "Next steps:"
+echo "  • Work through a section: /tech-design think rollout"
+echo "  • Draft a section: /tech-design draft data-model"
+echo "  • Natural language also works: \"Let's think through the rollout plan\""
+```
+
+### 7. Offer Guided Walkthrough
+
+If multiple critical sections missing:
+
+```bash
+echo ""
+echo "Want me to walk you through these? I can:"
+echo "  1. Guide you through each critical section"
+echo "  2. Let you pick which to work on"
+echo "  3. Just show the list (already done)"
+```
+
+If user chooses option 1, run `/tech-design think` for each critical section in order.
+
+## Section Criticality Logic
+
+```bash
+function get_criticality() {
+  local section=$1
+
+  case "$section" in
+    "Background"|"Proposal")
+      echo "CRITICAL"
+      ;;
+    "Risks & Mitigations")
+      echo "CRITICAL"
+      ;;
+    "Security Considerations")
+      # Critical if handling user input or sensitive data
+      if grep -qi "input\|user.*data\|sensitive\|auth" "$prd_path" 2>/dev/null; then
+        echo "CRITICAL"
+      else
+        echo "IMPORTANT"
+      fi
+      ;;
+    "Rollout Plan")
+      # Critical if user-facing
+      if grep -qi "user\|customer\|partner" "$prd_path" 2>/dev/null; then
+        echo "CRITICAL"
+      else
+        echo "IMPORTANT"
+      fi
+      ;;
+    "Data Model")
+      # Important if PRD mentions database
+      if grep -qi "database\|schema\|table" "$prd_path" 2>/dev/null; then
+        echo "IMPORTANT"
+      else
+        echo "OPTIONAL"
+      fi
+      ;;
+    "API Surface")
+      # Important if PRD mentions API
+      if grep -qi "API\|endpoint\|REST" "$prd_path" 2>/dev/null; then
+        echo "IMPORTANT"
+      else
+        echo "OPTIONAL"
+      fi
+      ;;
+    "Scope / Non-goals"|"Implementation Plan"|"Key Decisions")
+      echo "IMPORTANT"
+      ;;
+    *)
+      echo "OPTIONAL"
+      ;;
+  esac
+}
+```
+
+## Example Output (Early Stage)
+
+```
+📋 Tech Design Gaps Analysis
+
+✓ Complete:
+  • Background
+  • Open Questions
+
+⚠️  Started but empty:
+  • Proposal [CRITICAL]
+
+❌ Missing:
+  • Scope / Non-goals [IMPORTANT]
+  • Data Model [IMPORTANT] (PRD mentions database schema)
+  • API Surface [IMPORTANT] (PRD mentions REST endpoints)
+  • Risks & Mitigations [CRITICAL]
+  • Rollout Plan [CRITICAL] (user-facing feature)
+  • Security Considerations [CRITICAL] (handles user input)
+  • Implementation Plan [IMPORTANT]
+  • Key Decisions [IMPORTANT]
+
+Next steps:
+  • Work through a section: /tech-design think rollout
+  • Draft a section: /tech-design draft data-model
+  • Natural language also works: "Let's think through the rollout plan"
+
+Want me to walk you through these? I can:
+  1. Guide you through each critical section
+  2. Let you pick which to work on
+  3. Just show the list (already done)
+```
+
+## Example Output (Nearly Complete)
+
+```
+📋 Tech Design Gaps Analysis
+
+✓ Complete:
+  • Background
+  • Proposal
+  • Scope / Non-goals
+  • Data Model
+  • API Surface
+  • Risks & Mitigations
+  • Rollout Plan
+  • Security Considerations
+  • Implementation Plan
+
+⚠️  Started but empty:
+  • Key Decisions [IMPORTANT]
+
+❌ Missing:
+  • Metrics [OPTIONAL]
+  • Trade-off Analysis [OPTIONAL]
+
+Looking good! Just need to document your key decisions.
+
+Next steps:
+  • Add key decisions: /tech-design think decisions
+  • Ready to publish: /tech-design publish
+```
+
+## Example Output (Ready to Publish)
+
+```
+📋 Tech Design Gaps Analysis
+
+✓ Complete:
+  • Background
+  • Proposal
+  • Scope / Non-goals
+  • Data Model
+  • API Surface
+  • Risks & Mitigations
+  • Rollout Plan
+  • Security Considerations
+  • Implementation Plan
+  • Key Decisions
+
+❌ Missing:
+  • Metrics [OPTIONAL] (can be in thought doc only, surfaced via /ask in v2)
+
+🎉 All critical sections complete!
+
+Ready to publish:
+  /tech-design publish
+
+This will:
+  • Generate clean roll-up from your thought doc
+  • Create PR to codex with both docs
+  • TECH-DESIGN.md (reviewable roll-up)
+  • artifacts/thought-doc.md (your full working doc)
+```
+
+## Error Handling
+
+- **Thought doc not found:** Remind user to run `/tech-design start` first
+- **Thought doc has only template:** Suggest running `/tech-design draft` first
+- **Can't read PRD:** Skip context-based criticality, use defaults
+- **Section names don't match template:** Fuzzy match and warn if unexpected sections found
+
+## Helpful Hints
+
+If specific sections are commonly empty, provide targeted guidance:
+
+```
+⚠️  Risks & Mitigations is empty
+
+Common risks to consider:
+  • Performance: Will this handle expected load?
+  • Data: Migration issues? Data loss scenarios?
+  • Integration: What if dependent services fail?
+  • Rollout: What's the blast radius if it breaks?
+  • Security: Attack surface? Input validation?
+
+Want to explore these? /tech-design think risks
+```