measure

Intent

Quantify a specific metric for a target, providing a numerical value with explicit uncertainty bounds. This capability consolidates all estimation tasks (risk, impact, effort, etc.) into a single parameterized operation.

Success criteria:

• Numerical value provided for requested metric
• Uncertainty bounds explicitly stated
• Measurement method documented
• Units clearly specified

Compatible schemas:

• schemas/output_schema.yaml

Inputs

| Parameter | Required | Type | Description | |-----------|----------|------|-------------| | target | Yes | any | What to measure (system, code, entity, process) | | metric | Yes | string | The metric to quantify (risk, complexity, effort, size, etc.) | | unit | No | string | Unit of measurement (optional, inferred if not provided) | | method | No | string | Measurement approach (heuristic, statistical, model-based) |

Procedure

1. Define the metric: Clarify exactly what is being measured

   • Establish clear definition of the metric
   • Identify appropriate unit of measurement
   • Determine measurement methodology

2. Gather measurement inputs: Collect data needed for measurement

   • Read relevant files, logs, or data sources
   • Identify quantifiable indicators
   • Note data quality and completeness

3. Calculate measurement: Apply measurement method to inputs

   • Use appropriate calculation for the metric type
   • For risk: probability * impact assessment
   • For complexity: cyclomatic, cognitive, or structural metrics
   • For effort: decomposition and estimation techniques

4. Establish uncertainty bounds: Quantify measurement confidence

   • Calculate or estimate lower and upper bounds
   • Consider data quality, method limitations
   • Express as confidence interval or range

5. Ground the measurement: Document evidence and method

   • Reference specific data points used
   • Note any assumptions in calculation
   • Document measurement methodology

Output Contract

Return a structured object:

value: number  # The measured value
uncertainty:
  lower: number  # Lower bound (confidence interval)
  upper: number  # Upper bound (confidence interval)
  type: string  # Type of uncertainty (confidence_interval, range, std_dev)
unit: string  # Unit of measurement
metric: string  # What was measured
method: string  # How it was measured
breakdown:  # Optional component breakdown
  - component: string
    value: number
confidence: 0..1  # Confidence in measurement accuracy
evidence_anchors: ["file:line", "data:source"]
assumptions: []

Field Definitions

| Field | Type | Description | |-------|------|-------------| | value | number | Primary measurement value | | uncertainty | object | Bounds and type of uncertainty | | unit | string | Unit of measurement | | metric | string | Name of measured property | | method | string | Measurement methodology used | | breakdown | array | Optional decomposition of measurement |

Examples

Example 1: Measure Code Complexity

Input:

target: "src/services/order_processor.rb"
metric: "complexity"
unit: "cyclomatic"

Output:

value: 24
uncertainty:
  lower: 22
  upper: 26
  type: "range"
unit: "cyclomatic complexity"
metric: "complexity"
method: "counted decision points (if, case, loops, &&, ||)"
breakdown:
  - component: "process_order method"
    value: 12
  - component: "validate_items method"
    value: 8
  - component: "calculate_totals method"
    value: 4
confidence: 0.9
evidence_anchors:
  - "src/services/order_processor.rb:15-120"
assumptions:
  - "Ruby control flow statements counted as decision points"
  - "Exception handling counted as branches"

Example 2: Measure Risk

Input:

target: "database migration: add user_preferences column"
metric: "risk"
method: "probability_impact"

Output:

value: 0.35
uncertainty:
  lower: 0.25
  upper: 0.50
  type: "confidence_interval_90"
unit: "risk score (0-1)"
metric: "risk"
method: "probability (0.5) * impact (0.7) normalized"
breakdown:
  - component: "probability_of_failure"
    value: 0.5
  - component: "impact_if_failed"
    value: 0.7
  - component: "data_loss_risk"
    value: 0.2
  - component: "downtime_risk"
    value: 0.4
confidence: 0.7
evidence_anchors:
  - "migrations/20240115_add_preferences.rb:1-25"
  - "tool:grep:similar_migrations"
assumptions:
  - "Table has ~1M rows based on user count"
  - "Migration will lock table during ALTER"
  - "No concurrent deployments during migration"

Verification

• [ ] Numerical value provided
• [ ] Uncertainty bounds are reasonable (lower < value < upper)
• [ ] Unit of measurement specified
• [ ] Method documented
• [ ] Evidence anchors reference measurement inputs

Verification tools: Read (to verify measurement inputs)

Safety Constraints

• mutation: false
• requires_checkpoint: false
• requires_approval: false
• risk: low

Capability-specific rules:

• Always provide uncertainty bounds, never claim false precision
• Document measurement methodology for reproducibility
• Flag when data is insufficient for reliable measurement
• Do not extrapolate beyond available data without noting assumptions

Composition Patterns

Commonly follows:

• observe - Measure properties of observed state
• detect - Measure characteristics of detected items
• retrieve - Measure retrieved data

Commonly precedes:

• predict - Measurements feed into predictions
• compare - Measurements enable quantitative comparison
• plan - Measurements inform risk-aware planning

Anti-patterns:

• Never use measure for binary detection (use detect)
• Avoid measure for categorical assessment (use classify)

Workflow references:

• See reference/workflow_catalog.yaml#digital_twin_sync_loop for risk measurement