@orderful/droid 0.25.2 → 0.26.0

package/src/tools/tech-design/skills/droid-tech-design/references/draft.md

@@ -0,0 +1,321 @@
+# Drafting Content
+
+**Trigger:** `/tech-design draft [section]` or user wants to generate content
+
+**Goal:** Use research doc as knowledge base, do additional exploration if needed, draft content into thought doc.
+
+**Security Note:** All user-provided inputs must be validated before use in shell commands. File paths and search patterns should be sanitized to prevent command injection.
+
+## Procedure
+
+### 1. Determine Scope
+
+```bash
+if [ -z "$section" ]; then
+  # Whole doc - draft all three initial sections
+  sections=("Background" "Proposal" "Open Questions")
+else
+  # Specific section
+  sections=("$section")
+fi
+```
+
+### 2. Load Research Doc
+
+**Research doc should exist** - created during `/tech-design start`.
+
+- Read research doc: `tech-design-{project}-research.md`
+- Extract relevant findings for the section being drafted
+- Use as knowledge base to inform draft
+
+**If research doc missing:**
+
+- Warn user: "Research doc not found. Run `/tech-design start` first to create research + thought docs."
+- Option to continue without research context
+
+### 3. Section-Specific Drafting
+
+For each section, use research doc findings and do additional exploration as needed.
+
+#### Background Section
+
+**Sources:**
+
+- PRD context from research doc → "Codex Context" section
+- Current state from research doc → "Similar Implementations"
+
+**Draft structure:**
+
+```markdown
+## Background
+
+### Problem
+
+{Why we're doing this - from PRD in research doc}
+
+### Current State
+
+{What exists today - from research doc discoveries}
+
+Reference findings from research:
+
+- Existing pattern: {file path from research}
+- Current approach: {description from research}
+
+### Context
+
+{Who needs this and why - from PRD}
+```
+
+#### Proposal Section
+
+**Sources:**
+
+- Architecture patterns from research doc
+- Integration points from research doc
+- Dependencies from research doc
+- Additional codebase exploration if needed
+
+**Draft structure:**
+
+```markdown
+## Proposal
+
+### Overview
+
+{High-level approach - informed by patterns in research doc}
+
+### Architecture
+
+{How it fits - reference integration points from research}
+
+Follows pattern from: {file path from research doc}
+Integrates with: {modules/services from research doc}
+
+### Data Model
+
+{Tables, schemas, types needed}
+
+### API Surface
+
+{New endpoints, methods, interfaces}
+
+### Implementation Approach
+
+{Step-by-step - leverage dependencies already identified in research}
+```
+
+**Additional exploration:**
+
+- If research doc doesn't have enough detail for a subsection, explore further
+- Add new discoveries back to research doc
+- Keep research doc as living knowledge base
+
+#### Open Questions Section
+
+**Sources:**
+
+- Scan PRD for ambiguous requirements
+- Gaps identified during proposal drafting
+- Missing information from research phase
+
+**Draft structure:**
+
+```markdown
+## Open Questions
+
+- [ ] {Question from PRD ambiguity}
+- [ ] {Question from technical exploration}
+- [ ] {Question about integration - e.g., "How should X handle Y?"}
+```
+
+### 4. Write to Thought Doc
+
+- Read existing thought doc
+- Replace or populate the section being drafted
+- Preserve any existing `@droid`/`@{user}` comments
+- Keep content outside the target section unchanged
+
+### 5. Output Summary
+
+```
+✓ Drafted: {section}
+
+Key points from research doc:
+  • {Finding 1 referenced}
+  • {Finding 2 referenced}
+
+{If additional exploration was done:}
+Additional discoveries:
+  • {New finding}
+  • {Added to research doc}
+
+Next steps:
+  • Review and refine: Open {thought_doc_path}
+  • Draft another section: /tech-design draft {section-name}
+  • Explore an idea: /tech-design think {topic}
+  • Check completeness: /tech-design gaps
+```
+
+## Section-Specific Guidance
+
+### Rollout Plan
+
+**Research doc reference:**
+
+- Deployment patterns
+- Feature flag setup (if found)
+- Monitoring/observability setup
+
+**Explore if needed:**
+
+- How are similar features rolled out?
+- What rollback mechanisms exist?
+
+**Draft:**
+
+```markdown
+## Rollout Plan
+
+### Phases
+
+| Phase | Audience | Timeline | Success Criteria |
+| ----- | -------- | -------- | ---------------- |
+| 1     | ...      | ...      | ...              |
+
+### Feature Flags
+
+{Based on feature flag patterns from research}
+
+### Rollback Strategy
+
+{Based on deployment patterns from research}
+
+### Monitoring
+
+{Based on observability setup from research}
+```
+
+### Data Model
+
+**Research doc reference:**
+
+- Existing database/storage patterns
+- Schema conventions
+- ORM/database tooling used
+
+**Explore if needed:**
+
+- Similar data models in codebase
+- Migration patterns
+
+**Draft:**
+
+```markdown
+## Data Model
+
+### Entities
+
+{Based on patterns from research doc}
+
+### Relationships
+
+{How entities relate}
+
+### Migrations
+
+{Following migration pattern from research}
+```
+
+### API Surface
+
+**Research doc reference:**
+
+- Existing API patterns (REST, GraphQL, gRPC, etc.)
+- Authentication/authorization patterns
+- Rate limiting setup
+
+**Explore if needed:**
+
+- Similar endpoint implementations
+- Validation patterns
+
+**Draft:**
+
+```markdown
+## API Surface
+
+### Endpoints
+
+{Following API pattern from research}
+
+### Authentication
+
+{Using auth pattern from research}
+
+### Validation
+
+{Based on validation patterns found}
+```
+
+### Security Considerations
+
+**Research doc reference:**
+
+- Auth patterns
+- Input validation setup
+- Audit logging
+
+**Explore if needed:**
+
+- How are similar features secured?
+- What security reviews exist?
+
+**Draft:**
+
+```markdown
+## Security Considerations
+
+### Authentication & Authorization
+
+{Based on auth patterns from research}
+
+### Input Validation
+
+{Based on validation patterns from research}
+
+### Audit Logging
+
+{Based on logging patterns from research}
+
+### Risk Assessment
+
+| Risk | Mitigation |
+| ---- | ---------- |
+| ...  | ...        |
+```
+
+## Error Handling
+
+- **Thought doc not found:** Remind user to run `/tech-design start` first
+- **Research doc not found:** Warn but offer to continue with limited context
+- **Section not recognized:** List valid sections, suggest `/tech-design gaps` to see what's missing
+- **Exploration fails:** Gracefully continue, note what couldn't be found
+
+## Example Output
+
+```
+✓ Loaded research doc for transaction-templates
+
+✓ Drafted: Proposal
+
+Key points from research doc:
+  • Template storage pattern: Found in {file path}
+  • Validation service: Integration point at {module}
+  • Dependencies: {library} already available
+
+Next steps:
+  • Review and refine: Open {brain_dir}/0-Inbox/plans/tech-design-transaction-templates.md
+  • Draft another section: /tech-design draft rollout
+  • Check completeness: /tech-design gaps
+```

package/src/tools/tech-design/skills/droid-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
+```