/spdd-analysis

Analyze a business requirement document against the current codebase, producing a strategic-level enriched context that combines business information, domain concept identification, high-level approach decisions, and risk analysis — serving as high-quality input for /spdd-reasons-canvas. This phase focuses on the "What" and "Why", leaving the "How" to the REASONS Canvas phase.

Input: The argument after /spdd-analysis is a business requirement description or file reference.

Input can be provided in two ways:

1. Text description: Direct text describing the requirement
2. File/folder reference: Using @ to reference files or folders containing requirements

Examples:

# File reference
/spdd-analysis @requirements/token-usage-billing-story.md

# Text description
/spdd-analysis Implement monthly billing summary report for customers with usage breakdown

# Combined
/spdd-analysis @requirements/billing-report.md additionally needs CSV export support

Steps

1. Validate and consolidate business input

   a. If no input provided, use the AskUserQuestion tool (open-ended, no preset options) to ask:

   "Please provide the business requirement document or description (you can use text, @file references, or both)."

   IMPORTANT: Do NOT proceed without business input.

   b. If input contains @ file/folder references:

   • Read ALL referenced files completely using the Read tool
   • For folder references, read all relevant files within the folder
   • Consolidate all file contents into a unified business context

   c. Combine all context sources:

   • Merge text descriptions with file contents
   • Preserve the complete information from all sources — do NOT summarize or truncate

   d. Context Integrity Check:

   • Verify all @ references were successfully read
   • If any file cannot be read, report the error and ask user to provide alternative
   • Confirm the consolidated context contains sufficient information to proceed

2. Concept-driven codebase exploration

   Do NOT exhaustively read the entire codebase — this does not scale. Instead, use a concept-driven approach: first build a lightweight project fingerprint, then extract search concepts from the business requirement, and finally explore only the relevant parts of the codebase in depth.

   a. Project fingerprint (lightweight bootstrap — always do first):

   • Read the primary build/dependency file (ONE file: e.g., build.gradle, pom.xml, package.json, requirements.txt, go.mod) to detect the tech stack, framework, and key dependencies
   • List the top-level directory structure (directory names only, not file contents) to understand the project layout and layering conventions
   • Read the main configuration file (e.g., application.yml, .env, next.config.js) to understand infrastructure choices (DB, caching, messaging, etc.)
   • This step should be fast and touch only 2–3 files

   b. Extract search concepts from business input: Before touching any domain code, analyze the business requirement from Step 1 to extract:

   • Domain nouns: entity/concept names that likely map to code (e.g., "customer", "bill", "pricing plan", "subscription", "quota")
   • Action verbs: operations that likely map to endpoints or services (e.g., "submit usage", "calculate bill")
   • API surfaces: explicit paths, event names, or queue names mentioned (e.g., POST /api/usage)
   • Technical hints: mentioned technologies, patterns, or domain-specific terms (e.g., "monthly reset", "overage rate", "token")

   These extracted concepts become the search scope for all subsequent exploration.

   c. Targeted schema exploration (scoped by concepts):

   • Search migration/schema files for tables whose names match the extracted domain nouns — do NOT read all migrations
   • Read ONLY the matched migrations or schema definitions
   • Follow foreign key relationships one hop outward from matched tables to capture boundary context (e.g., if bills references customers, read the customers table definition too)
   • If using an ORM, search for entity/model classes matching the same concept names