SOLO

Executive Summary

This document describes a structured workflow for AI-assisted software development using Cursor IDE with custom slash commands. The workflow emphasizes planning before coding, iterative critique, and quality gates before deployment. It was refined over multiple iterations of a full-stack application migration.

---

Core Philosophy

01. Plan First, Code Second

Never jump directly into implementation. Every significant piece of work goes through a planning phase that includes analysis, explicit design decisions, and self-critique.

02. Trust But Verify

The AI agent does the heavy lifting, but the human maintains control through explicit approval gates, structured reviews, and quality checks before commits.

03. Persistent Context

Sessions can span days or weeks. Context preservation is critical: session memory files capture state, and the AI can resume work without re-explaining the project.

04. API-First Design

The API contract is the source of truth. Before implementation begins, define all endpoints and schemas. The .API/ folder contains the canonical contract enabling independent technology choices.

05. Test-Driven Development

Production code is a liability without tests. Quality is a prerequisite. Write tests before implementation—they define "done". No code ships without passing the full test suite.

06. Security-First Architecture

Security is not a feature; it is an architectural constraint. Auth and RBAC are designed before feature code. Zero-Trust is default. Security Audits are mandatory gates.

---

The Command System

Custom slash commands in .cursor/commands/ define specialized agent personas. Each command transforms the AI into a domain expert. Click a card to view the protocol specification.

---

Detailed Phase Breakdown

Phase 1: Resume & Orient

Command: /resume

Start every session by loading context from the session memory file. The AI reads .tmp/SESSION_MEMORY.md and orients itself to project state, critical knowledge, and user preferences.

Phase 2: Architect & Plan

Command: /architect

For significant work, generate a technical specification before implementation. The architect persona produces structured documents including diagrams, API contracts, and security considerations. Outputs a comprehensive plan answering "what" and "why".

Phase 2b: Design the Experience

Command: /design

When UI is impacted, invoke the UX Oracle. Produces an "Experience Manifesto" utilizing JTBD Deep-Dives, Shadow Data Extraction, and Cognitive Load Mapping.

Phase 3: Critique the Plan

Command: /critique

Turns the AI against its own plan. Hunts for gaps, brittle design, code smells, and security concerns. Flags anti-patterns like "Gold-Plating," "Abstractions for One," and "Locked File Modification."

Phase 4: Revise with Best Practices

Command: /revise

Address every critique item. Does NOT write implementation code. Specifies patterns and trade-offs. Iterates with Critique until the plan is ready.

Phase 5: Decompose into Tickets

Command: /tickets

Convert the approved plan into prioritized, actionable tickets. Each ticket is self-contained, vertically sliced, prioritized, and testable.

Phase 6: Implement

Command: /code

With an approved plan, implementation begins following strict TDD discipline. All failure modes must be handled with zero-bug tolerance and mandatory test coverage. No production code without unit, integration, or E2E tests.

Phase 6b: Refactor++

Command: /code++

For complex refactoring, use the Reference-First workflow. Create a complete source of truth before applying changes incrementally with full verification at each step.

Standalone Test Verification: /test ensures all tests are "green and clean."

Phase 7: Review

Command: /review

After implementation, conduct a formal code review. Produces a structured report with a Summary of Findings and a Health Score.

Phase 8: Fix

Command: /fix

Remediate all issues from the review systematically by severity. Runs full test suite after fixes.

Phase 9: Release

Commit with conventional messages, tag the release, save context with /memory, and deploy.

Phase 10: The Debug Loop (Sherlock Protocol)

Command: /sherlock

Even with rigorous orchestration, runtime issues occur. The Debug Loop provides a systematic protocol for Root Cause Analysis (RCA) when verification fails.

The Protocol

1. Isolate: Create a minimal reproduction case.
2. Investigate: Use /sherlock to trace logs, state, and dependencies.
3. Triage: Decide if it's a Minor Fix or Major Flaw.

Branching Logic

            ┌→ [Minor] → /critique → /revise → /fix → /test
/sherlock ──┤
            └→ [Major] → /architect → /critique → /revise → ...

Key Rule: Never apply a "blind fix". If /sherlock cannot explain why it broke, do not run /fix.

---

Key Principles in Practice

• 01. Explicit Approval Gates: Pause points for human review after every phase.
• 02. Context as Contract: .tmp/SESSION_MEMORY.md allows multi-session resiliency.
• 03. Quality Over Speed: Tests must pass before commits. Formatting is enforced.
• 04. Command Specialization: Different "expert personas" for focus and quality.

Adapting the Workflow

---

Protected Files: .lockedfiles

---

Conclusion

This workflow treats AI as a highly capable but supervised team member. The human provides strategic direction and approval; the AI provides deep analysis, consistent quality, and structured documentation. The result is production-grade code with a clear audit trail.