requirements-analysis

name	requirements-analysis
description	Use when analyzing functional specifications to extract KPIs, dimensions, grain, and constraints. Triggers: "analyze requirements", "extract KPIs", "analyze specification", "requirements summary", "identify dimensions", "define grain", "business requirements", "functional spec analysis", "clarification questions".
user-invocable	true

Skill: Requirements Analysis and Specification Extraction

Input Handling

• Markdown files (.md): Read the file content directly.
• Word documents (.docx): Ask the user to paste or convert the content. Do NOT attempt binary parsing.
• Detect the input language (Italian or English) and communicate in that language throughout the session.

Input / Output

Input	Functional specification document (.md or pasted text)
Output	<ProjectName>/spec/requirements_summary.md

Extraction Procedure

When analyzing the functional specifications document, perform the following extractions systematically:

1. Identify Metrics (Facts / KPIs)

• List ALL required quantitative metrics with their specific aggregation rules (SUM, AVERAGE, COUNT, etc.).
• For each KPI, specify:
  • Name (in English for code, original language for descriptions)
  • Aggregation type (additive, semi-additive, non-additive)
  • Formula or calculation logic (if provided)
  • Format (currency, percentage, integer, etc.)
  • Time intelligence requirements (YTD, PY, MoM, etc.)

2. Identify Dimensions

• List ALL qualitative attributes used for filtering or grouping.
• For each dimension, identify:
  • Attributes (columns for filtering/grouping)
  • Hierarchies (drill-down paths, e.g., Area → Country → Customer)
  • Cardinality estimate (high/medium/low)
  • Whether it's shared across multiple fact tables (conformed dimension per Kimball)

3. Determine Granularity (Grain)

• Explicitly state the lowest level of detail (grain) for each Fact table.
• Example: "One row per sales transaction per day per customer" vs. "One row per month per area".
• If the specs are ambiguous about grain, flag it and ask the user.

4. Extract RLS Rules

• Map out any Row-Level Security requirements:
  • Which user roles exist
  • Which dimension tables each role filters
  • The DAX filter expression logic
• If (and ONLY if) RLS is in scope, reference .github/references/security-rls-best-practices.md to ensure:
  • Least privilege and explicit allow/deny behavior is specified
  • The identity mechanism is clear (e.g., USERNAME(), USERPRINCIPALNAME(), CUSTOMDATA())
  • RLS is designed to filter Dimensions (with propagation to Facts) rather than filtering Facts directly
• Context optimization: if RLS is NOT mentioned/required, do NOT load security references.
• If no RLS is mentioned, explicitly note: "No RLS requirements detected."

5. Identify Fact Table Separation

• Determine if facts should be in separate tables (e.g., Sales Fact vs. Budget Fact).
• Identify the grain of each fact table independently.
• Note any many-to-many relationships that may require bridge tables.

6. Detect Dynamic Switching Requirements

• Explicitly detect whether the report requires field parameters for dynamic switching of dimensions, measures, or mixed field sets.
• For each requested dynamic switch, capture:
  • Business intent: what the user wants to change dynamically and why
  • Parameter scope: dimension switch, measure switch, or mixed switch
  • Target visuals: which charts, tables, or matrices consume the parameter
  • Selection behavior: single-select or multi-select
  • Default selection: which field should be active when the report opens
• For measure-switch requirements, also capture the allowed analysis context:
  • which dimensions are valid to keep on rows, columns, axis, legend, or table grouping when the measure parameter changes
  • why those dimensions remain semantically correct for every selectable measure
  • whether some dimensions are forbidden because one or more selectable measures do not propagate correctly through the active model relationships
• If the specification says users should "change the breakdown", "switch the axis", "change KPIs", or "choose what the visual shows", treat that as a field-parameter requirement unless the user says otherwise.

Validation Gate

Before declaring Step 1 complete, check:

• All KPIs have clear aggregation rules
• All dimensions have defined attributes
• Grain is explicitly defined for each fact table
• Data types are specified or inferrable for all fields
• RLS requirements are documented (or explicitly none)
• Time/period calculation requirements are clear (calendar/period boundary definitions, ordering, label semantics)
• Dynamic switching requirements are explicitly classified as regular slicers, field parameters, or not needed

If ANY of these are missing or ambiguous, flag them explicitly and ask the user before proceeding.

Critical Clarification Gate (MANDATORY)

For this workflow, the following clarifications are blocking and cannot remain implicit:

1. Period and calendar semantics used by cumulative or comparative calculations.
2. Numeric threshold/classification semantics for status-driven KPIs (including inclusive/exclusive boundaries).
3. Grain reconciliation semantics when metrics compare entities at different detail levels.

Required behavior:

• If one or more critical clarifications are unresolved, DO NOT accept Step 1 completion.
• If the user replies with generic approval (for example: "Proceed") without answering, ask targeted follow-up questions and keep the step pending.
• Only proceed when each critical clarification has either:
  • a concrete user answer, or
  • an explicit user-approved assumption recorded in workflow_state.json decision tracking.

Output Format

Present the analysis as a structured table:

### KPIs Identified
| # | KPI Name | Aggregation | Formula | Format | Time Intelligence |
|---|----------|------------|---------|--------|-------------------|

### Dimensions Identified
| # | Dimension | Key Attributes | Hierarchy | Shared? |
|---|-----------|---------------|-----------|---------|

### Fact Tables
| # | Fact Table | Grain | Related Dimensions |
|---|-----------|-------|-------------------|

### RLS Rules
| Role | Filtered Dimension | Filter Logic |
|------|-------------------|-------------|

### Dynamic Switching Requirements
| # | Intent | Parameter Scope | Target Visuals | Default Selection | Selection Mode | Allowed Context Dimensions |
|---|--------|-----------------|----------------|-------------------|----------------|----------------------------|

Save the primary artifact to <ProjectName>/spec/requirements_summary.md.