---
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: Priority levels (Essentiel/Important/Optionnel/Hors périmètre), 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. Coverage Matrix (MANDATORY)

BEFORE transitioning to step-02:

1. Re-read the original prompt/brief in its entirety
2. For EACH distinct feature/requirement mentioned:
   a. Create an entry in cadrage.coverageMatrix[]
   b. Assign it to mustHave, shouldHave, couldHave, or outOfScope
   c. Assign the module that will cover it (or null if cross-cutting)
3. Present the matrix to the client:
   "Voici la matrice de couverture de votre brief. {N} fonctionnalités identifiées :"
   (show as markdown table)
4. Ask: "Y a-t-il des éléments que j'ai oublié ou mal classé ?"
5. Iterate until the client confirms

**VALIDATION:** Every line of the original prompt must map to at least one coverageMatrix entry.
If a feature is in mustHave → it MUST have at least one UC in the corresponding module (verified in step-03).

### 10. Write Cadrage to Feature.json

Use ba-writer to enrich master feature.json. **Follow the STRUCTURE CARDS below exactly.**

> **STRUCTURE CARD: cadrage.stakeholders[]**
> ```json
> {
>   "role": "Fleet Manager",
>   "function": "Manages daily fleet operations",
>   "involvement": "decision-maker",
>   "tasks": ["Monitor vehicles", "Approve repairs", "Export reports"],
>   "frequency": "Daily",
>   "painPoints": ["Manual tracking in spreadsheets", "No real-time visibility"]
> }
> ```
> **MANDATORY fields:** `role`, `function`, `involvement`, `tasks`
> **involvement values:** `approver`, `decision-maker`, `consulted`, `informed`, `end-user`
> **FORBIDDEN fields:** Do NOT use `expertise`, `systemRole`, `description` (use `function` instead).

> **STRUCTURE CARD: cadrage.applicationRoles[]**
> ```json
> {
>   "role": "{App} Admin",
>   "description": "Full access to all modules",
>   "level": "admin",
>   "permissionPattern": "business.{app}.*"
> }
> ```
> **MANDATORY fields:** `role`, `level`, `permissionPattern`
> **level values:** `admin`, `manager`, `contributor`, `viewer`
> **FORBIDDEN fields:** Do NOT use `permissions` (use `permissionPattern`), `isDefault`.

> **STRUCTURE CARD: cadrage.risks[]**
> ```json
> {
>   "id": "RISK-001",
>   "type": "business|technical|organizational",
>   "description": "CSV data may contain duplicates and errors",
>   "probability": "high|medium|low",
>   "impact": "high|medium|low",
>   "priority": "critical|medium|low",
>   "mitigation": "Data cleaning phase before import, detailed error reports"
> }
> ```
> **MANDATORY fields:** `id` (pattern: RISK-NNN), `type`, `description`, `mitigation`
> **FORBIDDEN fields:** Do NOT use `risk` (name), `severity`. Use `id` + `description` + `priority`.

> **STRUCTURE CARD: cadrage.acceptanceCriteria[]**
> ```json
> { "id": "AC-001", "criterion": "All must-have features delivered and tested", "validated": false }
> ```
> **MANDATORY:** This section must NOT be omitted.

> **STRUCTURE CARD: cadrage.coverageMatrix[]**
> ```json
> {
>   "item": "User management with CRUD",
>   "category": "mustHave|shouldHave|couldHave|outOfScope|implicit",
>   "module": "Users",
>   "ucRef": "UC-UM-001",
>   "notes": "Foundation module, must be implemented first"
> }
> ```
> **MANDATORY fields:** `item`, `category`, `module`
> **category values:** `mustHave`, `shouldHave`, `couldHave`, `outOfScope`, `implicit` (camelCase)
> **FORBIDDEN fields:** Do NOT use `id`, `feature`, `priority`. Use `item` + `category`.

> **STRUCTURE CARD: cadrage.codebaseContext** — Must be a string, NOT an object.
> ```json
> "codebaseContext": "Greenfield project, no existing entities. SmartStack 2.1.0 with Extensions DbContext."
> ```

```
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 — use STRUCTURE CARD format}],
    globalScope: {
      mustHave: [{from Q3.x}],
      shouldHave: [{from Q3.x}],
      couldHave: [{from Q3.x}],
      outOfScope: [{from Q3.x}]
    },
    applicationRoles: [{from section 6 — use STRUCTURE CARD format}],
    risks: [{from section 8 — use STRUCTURE CARD format}],
    acceptanceCriteria: [{derived from scope — use STRUCTURE CARD format}],
    coverageMatrix: [{from section 9 — use STRUCTURE CARD format}],
    codebaseContext: "{string summary of codebase findings}"
  }
})

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

### 11. 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`
