dex-improve

name	dex-improve
description	Workshop one improvement idea into an implementation plan. Use when the user says 'let's flesh out idea-X', 'turn this into a plan', 'improve Dex's Y'. Not for ranking the whole backlog; use `dex-backlog`. Not for a PRD for the user's own product; use `product-brief`.

What This Command Does

In plain English: Your design partner for making Dex better. Three ways to use it:

1. Workshop an idea — Bring a fuzzy improvement idea, we'll shape it into a concrete plan
2. Review what's new — See recent Claude Code changes and how they could improve your system
3. Full capability audit — Find features you're not using that could help with your jobs-to-be-done

When to use it:

• "I have an idea but don't know how to implement it"
• "What new Claude Code features should I be using?"
• "Am I getting the most out of this system?"

How to run it:

/dex-improve                           # Shows menu of options
/dex-improve "your idea here"          # Jumps straight to workshopping

---

Entry Point

When invoked, offer these options:

How would you like to explore improvements?

1. **I have an idea** — Workshop a specific improvement
2. **What's new?** — Review Claude Code changes since [last check: DATE]
3. **Full audit** — Review all capabilities vs. your current usage

Or just describe your idea and I'll start workshopping.

If user provides $IDEA argument, skip to Mode 1 directly.

---

Mode 1: Workshop an Idea

Arguments: $IDEA — High-level description of what you want to improve

Phase 1: Understand

Parse the idea and frame it back:

1. Identify which Dex areas are involved:

   • Workflows (daily, weekly routines)
   • Automation (scripts, hooks, scheduled tasks)
   • Relationships (people tracking, meetings)
   • Task management (capture, flow, priorities)
   • Projects (planning, tracking, health)
   • Information retrieval (search, lookups)

2. State your understanding in 2-3 sentences

3. Note any ambiguity that needs clarification

Phase 2: Research + Capability Scan

Build context from multiple sources:

Internal (always check):

06-Resources/Learnings/                 # What you've learned so far
System/Skills/                       # Existing reusable behaviors
.claude/commands/                    # Existing commands that might overlap
System/pillars.yaml                  # Strategic priorities

External (when needed):

• Search web for latest Claude Code capabilities
• Check official docs at docs.anthropic.com

Check:

• Does similar functionality already exist?
• What existing patterns could we leverage?

Phase 3: Capability Match

Map requirements to optimal Claude Code features:

Requirement Pattern	Suggested Feature	Why
"Every time I edit X, do Y"	PostToolUse hook	Automatic trigger after tool completion
"Before doing X, check Y"	PreToolUse hook	Validation/confirmation gate
"At start of session, load Z"	SessionStart hook	Context injection
"Fast search while I work"	Explore sub-agent	Haiku model, runs in parallel
"Different perspective on X"	Custom sub-agent	Isolated context, specific focus
"Multi-step structured workflow"	Skill	Reusable behavior, always available
"Explicit invocation with steps"	Command	User-triggered workflow
"Connect to external service"	MCP integration	Tool access to external systems

Present the capability analysis to the user.

Phase 4: Expand

Suggest 2-3 adjacent improvements:

• Based on capability analysis, what else could we solve?
• Flag compound opportunities (build A, get B nearly free)
• Connect to existing gaps in the system
• Consider synergies with strategic pillars

Frame as: "While we're here, you might also consider..."

Phase 5: Refine

Drive toward concrete requirements through focused questions:

• Ask max 2-3 questions at a time
• Validate capability assumptions
• Confirm implementation approach preference
• Identify acceptance criteria

Loop between Research → Expand → Refine until requirements are solid.

Phase 6: Plan + Update

When requirements are firm:

1. Generate the plan document (see template below)
2. Save to plans/dex-improvement-[slug].md
3. Add any new patterns to 06-Resources/Learnings/
4. Add viable future ideas to backlog

---

Mode 2: What's New?

Review recent Claude Code changes and suggest improvements.

Process

1. Read state file: System/claude-code-state.json

   • If missing, this is first run — do a full scan instead

2. Fetch current changelog: Use WebSearch to find latest Claude Code changelog/releases

3. Compare: What's new since last_check date?

4. For each new feature, evaluate:

   • Is this relevant to Dex use cases?
   • What existing workflow could it improve?
   • Does it unlock something previously impossible?

5. Present findings:

📢 Claude Code Updates (since [last check date])

=== NEW CAPABILITIES ===

1. [Feature Name]
   - What it does: [description]
   - How it could help: [specific Dex improvement]
   - Effort to implement: Low/Medium/High

2. [Feature Name]
   ...

=== SUGGESTED IMPROVEMENTS ===

Based on these new capabilities, here's what you could build:

1. [Improvement name]
   - What: [description]
   - Why: [connects to which pillar/job-to-be-done]
   - Uses: [which new capability]

Want to workshop any of these? (Enter number or describe your own idea)

6. Update state file with current date and capabilities seen

State File Format

Location: System/claude-code-state.json

{
  "last_check": "2026-01-22",
  "last_version_seen": "1.0.30",
  "features_seen": [
    "hooks",
    "sub-agents",
    "skills",
    "commands",
    "mcp"
  ],
  "features_noted": [
    {
      "version": "1.0.30",
      "feature": "Async hooks",
      "date_seen": "2026-01-22"
    }
  ]
}

---

Mode 3: Full Capability Audit

Review all known Claude Code capabilities against your current system.

Process

1. Inventory current usage:

   • Scan .claude/ folder for hooks, commands, settings
   • Check System/Skills/ for skills
   • Check core/mcp/ for MCP integrations
   • Read 06-Resources/Learnings/ for known patterns

2. Load capability reference:

   • Use the capability match table (from Mode 1, Phase 3)
   • Search web for comprehensive Claude Code feature list if needed

3. Gap analysis:

=== CAPABILITY AUDIT ===

✅ Using Well:
- Commands (12 defined)
- Skills (person-lookup)

⚠️ Underutilized:
- Hooks — No hooks configured. Could automate:
  - Session start: Load context automatically
  - Post-edit: Update related files

❌ Not Using:
- Sub-agents — Could parallelize research tasks
- MCP beyond tasks — Calendar, email integrations possible

=== RECOMMENDATIONS ===

Ranked by impact vs. effort:

1. [High impact, low effort]
   - Add SessionStart hook to load daily context
   - Why: Saves 30 seconds every session
   - Connects to: [pillar]

2. [High impact, medium effort]
   ...

4. Offer to workshop any recommendation the user wants to pursue

---

Plan Output Template

Create at: plans/dex-improvement-[slug].md

# Dex Improvement: [Title]

**Created:** [Date]
**Status:** Planning → In Progress → Complete
**Pillar:** [pillar name if configured]

## Overview

[2-3 sentence summary of what we're improving and why]

## Requirements

- [ ] Requirement 1
- [ ] Requirement 2
- [ ] Requirement 3

## Capability Analysis

| Requirement | Implementation | Feature Type | Rationale |
|-------------|----------------|--------------|-----------|
| [req] | [how] | Hook/Sub-agent/Skill/Command | [why this approach] |

## Recommended Approach

[Which Claude Code features to use and why. Include trade-offs considered.]

## Implementation Steps

### Phase 1: [Foundation]
1. [Step]
2. [Step]

### Phase 2: [Core]
1. [Step]
2. [Step]

## Files to Create/Modify

| File | Action | Purpose |
|------|--------|---------|
| `path/to/file` | Create/Modify | [what] |

## Compound Opportunities

[What else we could solve while building this]

- [ ] [Adjacent improvement 1]
- [ ] [Adjacent improvement 2]

## Acceptance Criteria

- [ ] [Testable outcome 1]
- [ ] [Testable outcome 2]

## Questions Resolved

- Q: [Question that came up]
- A: [How we decided]

---

Example Interactions

Mode 1: Workshop

/dex-improve "Better meeting action item capture"

> **Understanding:** You want to improve how action items flow from meetings 
> into your task system. This touches workflows (meeting processing) and 
> task management (capture and routing).
>
> **Current state** (from Learnings):
> - Meeting notes go to `00-Inbox/Meetings/`
> - Action items manually extracted during review
>
> **Capability scan:**
> - PostToolUse hook could auto-trigger processing after meeting note creation
> - Sub-agent could parallel process: action items, follow-ups, person updates
>
> **Questions:**
> 1. Where are items getting lost—during capture, or in follow-through?
> 2. Would auto-drafted follow-up emails be valuable?

Mode 2: What's New

/dex-improve
> [selects "What's new?"]

> 📢 Claude Code Updates (since 2026-01-15)
>
> === NEW CAPABILITIES ===
> 1. Async Hooks — Hooks can now run without blocking
>    - How it could help: Faster session startup
>    - Effort: Low
>
> === SUGGESTED IMPROVEMENTS ===
> 1. Non-blocking context loading
>    - What: Load learnings/preferences in background
>    - Why: Snappier session starts
>
> Want to workshop any of these?

Mode 3: Full Audit

/dex-improve
> [selects "Full audit"]

> === CAPABILITY AUDIT ===
>
> ✅ Using Well: Commands (12), Skills (1)
> ⚠️ Underutilized: Hooks (0 configured)
> ❌ Not Using: Sub-agents, Advanced MCP
>
> === TOP RECOMMENDATION ===
> Add SessionStart hook — saves context loading time every session
>
> Want me to workshop this improvement?

---

Behaviors

Always Do

• Check internal patterns before suggesting new implementations
• Tie suggestions to user's pillars/jobs-to-be-done when configured
• Update state file after Mode 2 runs
• Offer concrete capability recommendations, not just ideas

Never Do

• Skip the research phase
• Suggest capabilities without explaining why they fit
• Output a plan before requirements are confirmed
• Make changes without explicit approval

---

Philosophy

This isn't just requirements gathering—it's capability-aware design. The goal is to help you leverage Claude Code's full potential while building exactly what you need, nothing more.

---

Track Usage (Silent)

Update System/usage_log.md to mark improvement workshop as used.

Analytics (Silent):

Call track_event with event_name improvement_workshopped and properties:

• idea_id

This only fires if the user has opted into analytics. No action needed if it returns "analytics_disabled".