Pi Choose Wisely

A pi-package for architectural decision management using the CHOICES.md framework.

Installation

pi install git:github.com/a-canary/pi-choose-wisely
# or
pi install /path/to/pi-choose-wisely

Skills

/choose-wisely

Clarify project vision, mission, UX, operations, and architectural decisions in CHOICES.md.

• Auto-bootstraps from existing docs if CHOICES.md missing
• Validates with cascading impact review after changes
• Runs structural audit automatically

/choose-wisely                              # Bootstrap or show status
/choose-wisely add OAuth authentication     # Add a choice
/choose-wisely change database to Postgres  # Modify a choice
/choose-wisely audit                        # Full validation

/choose-wisely:replan

Gap analysis: compare CHOICES.md against current implementation state, generate PLAN.md for next phase.

/choose-wisely:replan                       # Analyze gaps, generate plan

CHOICES.md Structure

8 sections in priority order:

| Section | Prefix | What goes here | |---------|--------|----------------| | Mission | M- | Why we exist, values, principles | | User Experiences | UX- | Core user journeys, interactions | | Features | F- | Specific capabilities | | Operations | O- | Automation, SLAs, workflows | | Data | D- | Storage decisions, schemas | | Architecture | A- | System design (tool-agnostic) | | Technology | T- | Tech stack, libraries (names tools) | | Implementation | I- | Dev practices, standards |

Choice Format

### A-0012: Event-driven architecture for order processing
Supports: F-0003, O-0002

Use message queue for order events. Decouples billing, inventory,
and shipping services. Enables async processing for traffic spikes.

Rules:

• Position = Priority (higher constrains lower)
• Supports: required on every choice (except top)
• Architecture is tool-agnostic, Technology names tools

Helper Modules

Loaded on-demand by the main skill:

• lib/bootstrap.md — Scan docs, extract choices
• lib/audit.md — 8 validation checks
• lib/cascade.md — 3-check impact review
• lib/interview.md — Planning questions by category

Templates

• templates/CHOICES.md — Empty template with 8 sections
• templates/PLAN.md — Phased implementation plan

License

MIT