---
name: step-01-cadrage
description: Application/module framing - context, problem, stakeholders, scope, application roles
model: opus
next_step: steps/step-02-decomposition.md
---

# Step 1: Cadrage (Framing)

## MANDATORY EXECUTION RULES

- ALWAYS use ULTRATHINK mode for this step
- ALWAYS apply the 5 Elicitation Techniques from `_shared.md`
- NEVER accept vague answers — probe deeper
- NEVER define entities or business rules here — that's per-module in step-03
- ALL questions via AskUserQuestion tool (NEVER as text dumps)
- ALL communication in `{language}` (from feature.json.metadata.language)

## YOUR TASK

Frame the analysis scope at the **application level**: understand the problem, stakeholders, scope, and define application-level roles. This step works for both multi-module applications and single modules.

**Key difference from old step-01-analyse:** This step does NOT define entities, business rules, or process flows. Those are per-module and handled in step-03.

---

## EXECUTION SEQUENCE

### 1. Read Current State

```
ba-reader.findFeature({feature_id})
→ Read metadata: application, language, workflow.mode, useCase
→ Read cadrage section (if resuming)
```

IF cadrage already completed (status = "framed"):
  Display: "Cadrage already completed. Loading next step."
  Load: steps/step-02-decomposition.md
  STOP

### 2. Codebase Pre-Research

> **Same pattern as previous step-01-analyse.** Understand what already exists.

**Phase 2a: MCP Tools (if available)**
```
IF mcp_available:
  Call: mcp__smartstack__analyze_extension_points
  → Discover existing modules, entities, services

  Call: mcp__smartstack__api_docs
  → Existing API documentation

  Call: mcp__smartstack__validate_conventions
  → Validate application/module naming

  Store findings in {codebase_context}
```

**Phase 2b: Parallel Agents (unless economy_mode)**
```
IF NOT economy_mode:
  Launch 3 agents in parallel:
    Agent 1: Search for existing domain entities (Glob: **/Domain/**/*.cs)
    Agent 2: Search for existing services/integrations (Grep: IService, IRepository)
    Agent 3: Search for existing page patterns (Glob: **/pages/business/**/*.tsx)

  Merge findings into {codebase_context}
```

**Phase 2c: Economy Mode**
```
IF economy_mode:
  Use Glob/Grep directly (no subagents)
  Quick scan of Domain/, Application/, pages/ directories
```

### 3. Application-Level Questionnaire (application mode)

> **Only loaded when workflow.mode = "application"**

Load: `questionnaire/00-application.md`

Ask questions in batches of max 4 via AskUserQuestion:

**Batch 1 (Q0.1-Q0.2): Application Identity**
- Application name (PascalCase)
- Application purpose (1-2 sentences)

**Batch 2 (Q0.3-Q0.4): Module Landscape**
- How many modules envisioned
- Which are must-have for first release

**Batch 3 (Q0.5-Q0.6): Application Roles**
- Standard 4-tier roles or customize
- Module-specific role restrictions

**Batch 4 (Q0.7-Q0.8): Cross-Module**
- Business processes spanning modules
- Default role for new users

After each batch: Apply ULTRATHINK + Elicitation Techniques.

### 4. Core Questionnaires (always)

Load these categories in order:

**Category 01 - Context** (`questionnaire/01-context.md`)
- Q1.1-Q1.4: Problem, AS-IS, TO-BE, trigger
- 1 AskUserQuestion batch

**Category 02 - Stakeholders** (`questionnaire/02-stakeholders.md`)
- Q2.1-Q2.8: Roles, tasks, frequency, pain points
- 2 AskUserQuestion batches
- ULTRATHINK: Map stakeholders to application roles

**Category 03 - Scope** (`questionnaire/03-scope.md`)
- Q3.1-Q3.8: MoSCoW prioritization, flows, errors
- 2 AskUserQuestion batches
- ULTRATHINK: Ensure scope items map to modules

### 5. Conditional Questionnaires

Based on feature description analysis, load additional categories:

| Condition | Category | Questionnaire |
|-----------|----------|---------------|
| Security concerns mentioned | 06 | `questionnaire/06-security.md` |
| Integration with external systems | 05 | `questionnaire/05-integrations.md` |
| Performance requirements | 08 | `questionnaire/08-performance.md` |
| Technical constraints | 09 | `questionnaire/09-constraints.md` |
| Documentation requirements | 10 | `questionnaire/10-documentation.md` |

> **Categories 04 (data), 07 (ui), 11 (data-lifecycle), 12 (migration), 13 (cross-module) are per-module and loaded in step-03.**

### 6. Application Roles Definition

> **Define roles at the APPLICATION level, not per-module.**

IF application mode AND roles not yet defined from Q0.5:
  Propose the standard 4-tier roles:

```
Application Roles for {application_name}:

| Role | Level | Default Permissions |
|------|-------|-------------------|
| {App} Admin | admin | business.{app}.* (wildcard) |
| {App} Manager | manager | read, create, update, assign |
| {App} Contributor | contributor | read, create, update |
| {App} Viewer | viewer | read only |
```

Ask via AskUserQuestion:
```
question: "Ces 4 rôles conviennent-ils pour {application_name} ?"
header: "Rôles"
options:
  - label: "Oui, parfait"
    description: "Utiliser les 4 rôles standards tels quels"
  - label: "Renommer"
    description: "Garder 4 niveaux mais personnaliser les noms"
  - label: "Personnaliser"
    description: "Modifier le nombre ou les permissions des rôles"
```

IF single-module mode:
  Same role definition but inferred from stakeholders

### 7. Proactive Suggestions

> **Same pattern as previous step-01.** Load suggestion catalog.

Load: `patterns/suggestion-catalog.md`

1. Analyze scope items and stakeholder needs
2. Match against catalog patterns
3. Present top 3-4 suggestions via AskUserQuestion (multiSelect: true)
4. Store accepted suggestions in `suggestions[]`

### 8. Risk Analysis

Ask via AskUserQuestion:
```
question: "Quels sont les principaux risques pour ce projet ?"
header: "Risques"
multiSelect: true
options:
  - label: "Adoption utilisateur"
    description: "Risque que les utilisateurs n'adoptent pas le système"
  - label: "Qualité des données"
    description: "Données existantes incomplètes ou incohérentes à migrer"
  - label: "Dépendances techniques"
    description: "Dépendance à des systèmes externes ou des APIs"
  - label: "Complexité fonctionnelle"
    description: "Règles métier complexes ou mal documentées"
```

Classify per probability/impact:
- High/High → Critical (mitigation required)
- High/Low or Low/High → Medium (monitor)
- Low/Low → Low (accept)

### 9. Write Cadrage to Feature.json

Use ba-writer to enrich master feature.json:

```
ba-writer.enrichSection({
  featureId: {feature_id},
  section: "cadrage",
  data: {
    problem: {Q1.1 answer},
    asIs: {Q1.2 answer},
    toBe: {Q1.3 answer},
    trigger: {Q1.4 answer},
    stakeholders: [{mapped from Q2.x answers}],
    globalScope: {
      mustHave: [{from Q3.x}],
      shouldHave: [{from Q3.x}],
      couldHave: [{from Q3.x}],
      outOfScope: [{from Q3.x}]
    },
    applicationRoles: [{from section 6}],
    risks: [{from section 8}],
    acceptanceCriteria: [{derived from scope}],
    codebaseContext: {codebase_context}
  }
})

ba-writer.updateStatus({feature_id}, "framed")
```

### 10. Display Summary

```
## Cadrage Complete - {feature_id}

| Aspect | Count |
|--------|-------|
| Stakeholders | {count} |
| Must-have scope items | {count} |
| Application roles | {count} |
| Risks identified | {count} |
| Suggestions accepted | {count} |

### Application Roles
{table of roles with permission levels}

### Next Step
→ Module decomposition (step-02-decomposition.md)
```

---

## NEXT STEP

Load: `./step-02-decomposition.md`
