Feature Review

Table of Contents

• Philosophy
• When to Use
• When NOT to Use
• Quick Start
• 1. Inventory Current Features
• 2. Score and Classify
• 3. Generate Suggestions

Verification

Run make test-feature-review to verify scoring logic after changes.

• 4. Upload to GitHub
• Workflow
• Phase 1: Feature Discovery (`feature-review:inventory-complete`))
• Phase 2: Classification (`feature-review:classified`))
• Phase 3: Scoring (`feature-review:scored`))
• Phase 4: Tradeoff Analysis (`feature-review:tradeoffs-analyzed`))
• Phase 5: Gap Analysis & Suggestions (`feature-review:suggestions-generated`))
• Phase 6: GitHub Integration (`feature-review:issues-created`))
• Configuration
• Configuration File
• Guardrails
• Required TodoWrite Items
• Integration Points
• Output Format
• Feature Inventory Table
• Suggestion Report
• Feature Suggestions
• High Priority (Score > 2.5))
• Related Skills
• Reference

Feature Review

Review implemented features and suggest new ones using evidence-based prioritization. Create GitHub issues for accepted suggestions.

Philosophy

Feature decisions rely on data. Every feature involves tradeoffs that require evaluation. This skill uses hybrid RICE+WSJF scoring with Kano classification to prioritize work and generates actionable GitHub issues for accepted suggestions.

When To Use

• Roadmap reviews (sprint planning, quarterly reviews).
• Retrospective evaluations.
• Planning new development cycles.

When NOT To Use

• Emergency bug fixes.
• Simple documentation updates.
• Active implementation (use scope-guard).

Quick Start

1. Inventory Current Features

Discover and categorize existing features:

/feature-review --inventory

2. Score and Classify

Evaluate features against the prioritization framework:

/feature-review

3. Generate Suggestions

Review gaps and suggest new features:

/feature-review --suggest

4. Research-Enriched Scoring

Use tome plugin to adjust scores with external evidence:

/feature-review --research

5. Upload to GitHub

Create issues for accepted suggestions:

/feature-review --suggest --create-issues

Workflow

Phase 1: Feature Discovery (feature-review:inventory-complete)

Identify features by analyzing:

1. Code artifacts: Entry points, public APIs, and configuration surfaces. 2. Documentation: README lists, CHANGELOG entries, and user docs. 3. Git history: Recent feature commits and branches.

Output: Feature inventory table.

Phase 2: Classification (feature-review:classified)

Classify each feature along two axes:

Axis 1: Proactive vs Reactive

Axis 2: Static vs Dynamic

See classification-system.md for details.

Phase 3: Scoring (feature-review:scored)

Apply hybrid RICE+WSJF scoring:

Feature Score = Value Score / Cost Score

Value Score = (Reach + Impact + Business Value + Time Criticality) / 4
Cost Score = (Effort + Risk + Complexity) / 3

Adjusted Score = Feature Score * Confidence

Scoring Scale: Fibonacci (1, 2, 3, 5, 8, 13).

Thresholds:

• > 2.5: High priority.
• 1.5 - 2.5: Medium priority.
• < 1.5: Low priority.

See scoring-framework.md for the framework. See multi-metric-evaluation-methodology.md when one model is not enough: it covers how to combine RICE, WSJF, and Kano, where each model fits, and how to reconcile conflicting signals.

Phase 4: Tradeoff Analysis (feature-review:tradeoffs-analyzed)

Evaluate each feature across quality dimensions:

See tradeoff-dimensions.md for criteria.

Phase 4.5: Research Enrichment (feature-review:research-enriched)

Triggered by: --research flag. Requires tome plugin.

Use tome's multi-source research to adjust scoring factors with external evidence. This phase runs between tradeoff analysis and gap analysis.

1. Dispatch research: For each feature, construct research topics and dispatch tome channels (code-search, discourse, papers, triz) in parallel. 2. Synthesize findings: Merge results across channels using tome:synthesize. 3. Calculate deltas: Map findings to scoring factor adjustments using channel-to-factor mapping. 4. Apply deltas: Adjust initial scores by research deltas, clamp to Fibonacci scale, respect max_delta. 5. Present evidence: Show adjustment table with evidence sources and rationale.

See research-enrichment.md for the full enrichment protocol, delta calculation, and graceful degradation behavior.

Graceful degradation: If tome is not installed, prints a warning and proceeds with initial scores unchanged.

Phase 5: Gap Analysis & Suggestions (feature-review:suggestions-generated)

1. Identify gaps: Missing Kano basics. 2. Surface opportunities: High-value, low-effort features. 3. Flag technical debt: Features with declining scores. 4. Recommend actions: Build, improve, deprecate, or maintain.

Phase 6: GitHub Integration (feature-review:issues-created)

1. Generate issue title and body from suggestions. 2. Apply labels (feature, enhancement, priority/*). 3. Link to related issues. 4. Confirm with user before creation.

Deferred capture for high-scoring suggestions: After the user confirms which suggestions to act on, any high-scoring suggestion (score > 2.5) that is not acted on should be preserved as a deferred item. Run once per skipped high-scoring suggestion:

python3 scripts/deferred_capture.py \
  --title "<suggestion title>" \
  --source feature-review \
  --context "RICE score: <score>. <description>"

This runs automatically without prompting the user. Suggestions with scores of 2.5 or below do not need to be captured.

Configuration

Feature-review uses opinionated defaults but allows customization.

Configuration File

Create .feature-review.yaml in project root:

# .feature-review.yaml
version: 1.9.3

# Scoring weights (must sum to 1.0)
weights:
  value:
    reach: 0.25
    impact: 0.30
    business_value: 0.25
    time_criticality: 0.20
  cost:
    effort: 0.40
    risk: 0.30
    complexity: 0.30

# Score thresholds
thresholds:
  high_priority: 2.5
  medium_priority: 1.5

# Tradeoff dimension weights (0.0 to disable)
tradeoffs:
  quality: 1.0
  latency: 1.0
  token_usage: 1.0
  resource_usage: 0.8
  redundancy: 0.5
  readability: 1.0
  scalability: 0.8
  integration: 1.0
  api_surface: 1.0

See configuration.md for options.

Guardrails

These rules apply to all configurations:

1. Minimum dimensions: Evaluate at least 5 tradeoff dimensions. 2. Confidence requirement: Review scores below 50% confidence. 3. Breaking change warning: Require acknowledgment for API surface changes. 4. Backlog limit: Limit suggestion queue to 25 items.

Required TodoWrite Items

1. feature-review:inventory-complete 2. feature-review:classified 3. feature-review:scored 4. feature-review:tradeoffs-analyzed 5. feature-review:research-enriched (if --research) 6. feature-review:suggestions-generated 7. feature-review:issues-created (if requested)

Integration Points

• `imbue:scope-guard`: Provides Worthiness Scores for suggestions.
• `sanctum:do-issue`: Prioritizes issues with high scores.
• `superpowers:brainstorming`: Evaluates new ideas against existing features.
• `tome:research`: Multi-source research for score enrichment (optional, --research).

Output Format

Feature Inventory Table

| Feature | Type | Data | Score | Priority | Status |
|---------|------|------|-------|----------|--------|
| Auth middleware | Reactive | Dynamic | 2.8 | High | Stable |
| Skill loader | Reactive | Static | 2.3 | Medium | Needs improvement |

Research-Enriched Table (with --research)

| Feature | Type | Score | Adj. | Priority | Evidence |
|---------|------|-------|------|----------|----------|
| Auth    | R/D  | 2.8   | 3.1  | High     | 3 sources |
| Loader  | R/S  | 2.3   | 2.3  | Medium   | none      |

## Research Evidence

### Code Search (GitHub)
- 12 implementations, avg 340 stars
- **Reach**: +1 (broad adoption)

### Discourse (HN/Reddit)
- 47 mentions, 78% positive
- **Impact**: +1 (strong demand)

Suggestion Report

## Feature Suggestions

### High Priority (Score > 2.5)

1. **[Feature Name]** (Score: 2.7)
   - Classification: Proactive/Dynamic
   - Value: High reach
   - Cost: Moderate effort
   - Recommendation: Build in next sprint

Related Skills

• imbue:scope-guard: Prevent overengineering.
• sanctum:pr-review: Code-level review (different scope: this

skill prioritizes feature ideas, pr-review reviews diffs).

Reference

• [scoring-framework.md](modules/scoring-framework.md): RICE+WSJF hybrid.
• [classification-system.md](modules/classification-system.md): Axes definition.
• [tradeoff-dimensions.md](modules/tradeoff-dimensions.md): Quality attributes.
• [research-enrichment.md](modules/research-enrichment.md): tome-driven score deltas, channel-to-factor mapping, graceful degradation.
• [multi-metric-evaluation-methodology.md](modules/multi-metric-evaluation-methodology.md): Combining RICE, WSJF, and Kano when no single model suffices.
• [configuration.md](modules/configuration.md): Customization options.

Classification System

Features are classified along two orthogonal axes that determine architectural and UX implications.

Axis 1: Proactive vs Reactive

This axis describes when the feature acts relative to user intent.

Proactive Features

Definition: Anticipates user needs and acts before explicit request.

Characteristics:

• Runs in background or ahead of user action
• Requires prediction/inference of user intent
• May consume resources speculatively
• Higher latency tolerance (users don't wait)

Latency Tolerance:

• Background processing acceptable (seconds to minutes)
• User doesn't perceive delay directly
• Can be batched or deferred

Examples:

Tradeoffs:

Architecture Patterns:

• Event-driven / pub-sub
• Background workers
• Predictive models
• Eventual consistency acceptable

Reactive Features

Definition: Responds to explicit user input or system events.

Characteristics:

• Triggered by user action
• Must feel immediate
• Resources used on-demand
• Correctness over speculation

Latency Tolerance:

• Sub-100ms for UI feedback
• Sub-1s for completion
• User actively waiting

Examples:

Tradeoffs:

Architecture Patterns:

• Request/response
• Synchronous processing
• Strong consistency
• Direct invocation

Classification Decision Tree

Is the feature triggered by explicit user action?
├── Yes → Is immediate response critical?
│   ├── Yes → REACTIVE
│   └── No → Could be either (consider UX goals)
└── No → Does it require user data/context?
    ├── Yes → PROACTIVE (with data)
    └── No → PROACTIVE (autonomous)

Axis 2: Static vs Dynamic

This axis describes how feature data changes over time.

Static Features

Definition: Data changes incrementally through explicit updates.

Characteristics:

• Version-controlled or release-based updates
• Can be cached aggressively
• Deterministic lookups
• Stale data possible but predictable

Update Pattern:

• Deploy-time updates
• Batch processing
• Periodic refresh
• Manual triggers

Storage Models:

Lookup Cost: O(1) or O(log n), highly cacheable

Examples:

Tradeoffs:

Dynamic Features

Definition: Data changes continuously through ongoing operations.

Characteristics:

• Real-time or near-real-time updates
• Limited caching opportunity
• Query-based lookups
• Consistency challenges

Update Pattern:

• Event-driven updates
• Streaming ingestion
• Live queries
• Continuous sync

Storage Models:

Lookup Cost: O(log n) to O(n), cache hit-rate varies

Examples:

Tradeoffs:

Classification Decision Tree

Does the data change based on user actions in real-time?
├── Yes → DYNAMIC
└── No → Is freshness critical (< 1 hour)?
    ├── Yes → DYNAMIC
    └── No → Could the data be served from cache/CDN?
        ├── Yes → STATIC
        └── No → Consider hybrid (static + refresh)

The 2x2 Matrix

Combining both axes creates four feature archetypes:

                    STATIC                 DYNAMIC
              ┌─────────────────────┬─────────────────────┐
              │                     │                     │
   PROACTIVE  │   Predictive Cache  │   Smart Assistant   │
              │   (prefetch static) │   (live suggestions)│
              │                     │                     │
              │   Latency: Low      │   Latency: Medium   │
              │   Complexity: Low   │   Complexity: High  │
              │                     │                     │
              ├─────────────────────┼─────────────────────┤
              │                     │                     │
   REACTIVE   │   Reference Lookup  │   Interactive Query │
              │   (docs, configs)   │   (search, forms)   │
              │                     │                     │
              │   Latency: Very Low │   Latency: Low      │
              │   Complexity: Low   │   Complexity: Medium│
              │                     │                     │
              └─────────────────────┴─────────────────────┘

Archetype Details

Predictive Cache (Proactive and Static)

• Example: Prefetching documentation pages
• Pattern: Background worker loads static assets
• Complexity: Low - just scheduling and caching
• Risk: Wasted bandwidth if prediction wrong

Smart Assistant (Proactive and Dynamic)

• Example: AI-powered suggestions based on context
• Pattern: Real-time inference on streaming data
• Complexity: High - ML models, data pipelines
• Risk: Expensive, can be wrong, privacy concerns

Reference Lookup (Reactive and Static)

• Example: Loading skill definitions
• Pattern: Cache-first, fallback to file
• Complexity: Low - simple read operations
• Risk: Stale data if cache not invalidated

Interactive Query (Reactive and Dynamic)

• Example: Search across current repository
• Pattern: Query on demand, may use indexes
• Complexity: Medium - query optimization, indexing
• Risk: Variable latency, consistency windows

Classification for Common Features

Using Classification in Review

When reviewing features:

1. Identify current classification - What is it today? 2. Evaluate fit - Does classification match use case? 3. Consider migration - Would different classification improve UX? 4. Note tradeoffs - What would change with different classification?

Red Flags:

• Reactive feature with high latency → Consider proactive alternative
• Dynamic feature rarely changing → Could be static for performance
• Proactive feature often wrong → Consider reactive fallback
• Static feature causing staleness issues → Consider dynamic refresh

Configuration

Feature-review uses opinionated defaults but allows project-specific customization through a YAML configuration file.

Configuration File Location

Create .feature-review.yaml in your project root:

project/
├── .feature-review.yaml    # Configuration file
├── src/
└── ...

Full Configuration Schema

# .feature-review.yaml
# All values shown are defaults - only specify what you want to change

version: 1  # Schema version (required if file exists)

weights:
  value:
    reach: 0.25              # How many users affected
    impact: 0.30             # How much improvement per user
    business_value: 0.25     # OKR/strategic alignment
    time_criticality: 0.20   # Cost of delay
  cost:
    effort: 0.40             # Development time
    risk: 0.30               # Uncertainty/unknowns
    complexity: 0.30         # Technical difficulty

thresholds:
  high_priority: 2.5         # Score > 2.5 = implement soon
  medium_priority: 1.5       # Score > 1.5 = roadmap candidate
  confidence_warning: 0.5    # Scores below this get flagged

classification:
  default_type: reactive     # proactive | reactive
  default_data: static       # static | dynamic
  patterns:
    proactive_patterns: ["*auto*", "*suggest*", "*predict*", "*prefetch*"]
    dynamic_patterns: ["*session*", "*realtime*", "*live*", "*stream*"]

tradeoffs:
  quality: 1.0               # Correctness of results
  latency: 1.0               # Response time
  token_usage: 1.0           # Context efficiency (LLM-specific)
  resource_usage: 0.8        # CPU/memory consumption
  redundancy: 0.5            # Fault tolerance
  readability: 1.0           # Code maintainability
  scalability: 0.8           # Growth handling
  integration: 1.0           # Ecosystem fit
  api_surface: 1.0           # Contract stability

github:
  enabled: true
  auto_label: true
  label_prefix: "priority/"
  default_labels: [enhancement, feature-review]
  priority_labels:
    high: "priority/high"
    medium: "priority/medium"
    low: "priority/low"

inventory:
  scan_paths: ["commands/", "skills/", "agents/", "src/"]
  exclude_patterns: ["**/test*", "**/mock*", "**/__pycache__/**"]

output:
  format: markdown           # markdown | json | yaml
  include_rationale: true
  include_tradeoffs: true
  max_suggestions: 10

backlog:
  max_items: 25              # Maximum items (guardrail, cannot exceed 25)
  stale_days: 30
  auto_archive: false
  file: "docs/backlog/feature-queue.md"

Minimal Configuration Examples

Startup (Move Fast)

version: 1
thresholds:
  high_priority: 2.0
  medium_priority: 1.0
tradeoffs:
  redundancy: 0.3
  scalability: 0.5
backlog:
  max_items: 15

Enterprise (Stability First)

version: 1
thresholds:
  high_priority: 3.0
  confidence_warning: 0.7
tradeoffs:
  api_surface: 1.5
  redundancy: 1.2
  readability: 1.2

Project-Type Templates

Adjust tradeoff weights based on project type:

Guardrails (Always Enforced)

These rules apply regardless of configuration:

Environment Variable Overrides

Pattern: FEATURE_REVIEW_ and uppercase path with underscores.

FEATURE_REVIEW_HIGH_PRIORITY=3.0
FEATURE_REVIEW_GITHUB_ENABLED=false
FEATURE_REVIEW_OUTPUT_FORMAT=json

Configuration Validation

/feature-review --validate-config

Inheritance and Overrides

Directory-Level Config

Child configs inherit from parent and override specific values:

project/
├── .feature-review.yaml           # Project defaults
├── plugins/
│   └── .feature-review.yaml       # Plugin-specific overrides
└── experimental/
    └── .feature-review.yaml       # Experimental area config

Command-Line Overrides

/feature-review --threshold.high_priority=3.0
/feature-review --weights.value.impact=0.4
/feature-review --github.enabled=false

Migration Guide

From No Configuration

1. Run /feature-review with defaults 2. Review output for misaligned priorities 3. Create minimal .feature-review.yaml with only changed values

From Other Frameworks

Research Enrichment

Configure external research via the tome plugin. When enabled, research findings adjust scoring factors with evidence-backed deltas.

research:
  enabled: true
  channels:
    code_search: true          # GitHub code search
    discourse: true            # HN, Reddit, Lobsters
    papers: true               # arXiv, Semantic Scholar
    triz: true                 # Cross-domain analogical reasoning
  evidence_threshold: 0.3      # Minimum evidence to apply delta
  max_delta: 2                 # Max Fibonacci steps adjustment
  timeout_seconds: 120

When the tome plugin is not installed, --research prints a warning and proceeds with initial scores unchanged.

Advanced Patterns

Custom Scoring Dimensions

custom_dimensions:
  regulatory_compliance:
    weight: 1.5
    description: "Meets GDPR/SOC2/HIPAA requirements"
    scoring: {5: "Fully compliant", 3: "Minor gaps", 1: "Concerns"}

Conditional Configuration

Override weights based on feature classification:

conditional:
  proactive:
    tradeoffs:
      latency: 0.6
      resource_usage: 1.2
  dynamic:
    tradeoffs:
      redundancy: 1.2
      scalability: 1.2

Multi-Metric Evaluation Methodology

How to combine RICE, WSJF, Kano, and related models when prioritizing a feature backlog. Each model encodes a different assumption about what makes a feature worth building. This module shows the formulas, where each model fits, and how to combine them when no single model is enough on its own.

The Models at a Glance

Single-model use is rare in practice. Most teams converge on a hybrid: RICE for a base score, WSJF to raise time- critical items, Kano to gate basics. The rest of this module explains why and how.

Model 1: RICE

RICE = (Reach * Impact * Confidence) / Effort

Best for: large user-facing roadmaps where reach is measurable and a single team can absorb most items.

Worst for: backlogs dominated by infrastructure or compliance work where "reach" is meaningless or every item shares similar reach.

Worked example:

Feature: Auto-save drafts
  Reach:      8,000 users / quarter
  Impact:     1.0 (significant satisfaction)
  Confidence: 0.8
  Effort:     2 person-months

RICE = (8000 * 1.0 * 0.8) / 2 = 3200

Model 2: WSJF

Weighted Shortest Job First. From SAFe; treats prioritization as a cost-of-delay optimization.

WSJF = Cost_of_Delay / Job_Size

Cost_of_Delay = User_Value + Time_Criticality + Risk_Reduction
Job_Size      = Effort estimate

Each input uses a Fibonacci scale: 1, 2, 3, 5, 8, 13, 20.

Best for: backlogs with strong time pressure and many items where deferral has measurable cost. Common in SAFe-aligned organizations.

Worst for: small teams without explicit cost-of-delay numbers; reduces to "gut feel times Fibonacci".

Worked example:

Feature: GDPR consent banner
  User_Value:        5
  Time_Criticality:  20  (regulatory deadline)
  Risk_Reduction:    13
  Job_Size:          3

WSJF = (5 + 20 + 13) / 3 = 12.67

Compare with the auto-save example: WSJF would put auto-save at roughly (8 + 3 + 2) / 5 = 2.6, far below the GDPR item, even though RICE might rank them similarly. WSJF surfaces the deadline.

Model 3: Kano

Kano classifies features by user reaction, not score.

Source: Noriaki Kano et al., "Attractive Quality and Must-Be Quality" (1984).

Best for: avoiding the most common backlog mistake: shipping a Delighter while a Basic is still missing.

Worst for: numeric ranking. Kano gives categories, not scores. Pair it with RICE or WSJF for the actual ordering.

How to classify: present users with two questions per feature:

Functional:    "How would you feel if X were present?"
Dysfunctional: "How would you feel if X were absent?"

Each answered on a 5-point scale from "I like it" to "I dislike it". The answer pair maps to a Kano category via a fixed table (see Berger et al. 1993).

When Each Model Fits

Backlog has clear users and reach measurable?
  Yes -> RICE base
  No  -> skip RICE

Items have time-critical deadlines or value decay?
  Yes -> WSJF overlay
  No  -> skip WSJF

Backlog mixes table-stakes and aspirational features?
  Yes -> Kano gate
  No  -> skip Kano

Stakeholders need narrative buckets, not numbers?
  Yes -> MoSCoW translation layer
  No  -> skip MoSCoW

The Hybrid Used in This Skill

The feature-review skill combines RICE-like value / cost ratios, WSJF time criticality, and Kano gating. The formula is documented in modules/scoring-framework.md:

Value = weighted_avg(Reach, Impact, Business_Value, Time_Criticality)
Cost  = weighted_avg(Effort, Risk, Complexity)
Score = (Value / Cost) * Confidence

Kano enters as a hard gate before scoring. Any feature classified Basic that is absent today is bumped above the ranked list. The Score then orders everything else.

1. Classify every feature with Kano.
2. Pull all missing Basics to the top, ordered by user impact.
3. Score the rest with the Value/Cost formula.
4. Rank by Score; apply confidence multiplier.
5. Sensitivity-check the top 10 with +/- 20% weight perturbation.

Worked Example: Combining RICE, WSJF, and Kano

A team scores three candidates for the next sprint.

Candidates:
  A: Auto-save drafts
  B: GDPR consent banner
  C: Dark mode

Step 1 (Kano):
  A: Performance  (more frequent saves = more value)
  B: Basic        (legally required; absent today)
  C: Delighter

Step 2: Pull Basics. B is bumped to top of queue.

Step 3: Score A and C with hybrid:
  A: Value=4.75, Cost=2.67, Conf=0.8 -> 1.42
  C: Value=2.25, Cost=2.00, Conf=0.9 -> 1.01

Step 4: WSJF check on B for sizing:
  WSJF(B) = (5 + 20 + 13) / 3 = 12.67
  Confirms B is the largest cost-of-delay item.

Step 5: Sprint order:
  1. B (regulatory Basic)
  2. A (Score 1.42)
  3. C (Score 1.01)

Sensitivity: vary all weights by +/- 20%. Order is stable
in 18 of 20 perturbations. Fragile case: if Time
Criticality weight drops below 0.10, A and C swap. Action:
keep weight at the documented 0.20.

Anti-Patterns

Single-model orthodoxy. Picking RICE because the blog post said so, then shoehorning every item into a "reach" estimate that does not exist. If the model does not fit the input, change the model.

Hidden recalibration. Reweighting Impact from 1.0 to 3.0 mid-quarter to make a favored project rank higher. Track weight history in version control; flag mid-cycle changes.

Confidence rubber-stamping. Every item scored at Confidence 1.0. Confidence 1.0 means "I would bet the quarter on this estimate". Real backlogs cluster around 0.5 to 0.8.

Score inflation by Fibonacci jump. "It feels like an 8" when the difference between 5 and 8 should be a 60% larger investment. Force a comparison: "Is this 60% bigger than the last 5 we shipped?"

Aggregating Kano with a number. Kano is categorical. Adding "Basic = 5, Performance = 3, Delighter = 1" to a score creates the illusion of math.

Ignoring the Pareto front. When two items tie on Score but trade off on different axes (one scales reach, one buys time), report both and let humans pick. Do not break ties with a third decimal place.

Pitfalls Specific to AI/Plugin Backlogs

Reach is a mirage. Plugin reach is bounded by who installs the plugin, not by the addressable market. Use "installed teams" as the reach unit, not "potential users".

Effort underestimates evals. A new skill is not done when the prose is written. Add the cost of subagent test authoring to Effort or the score will overpromise.

Confidence collapses on token-driven features. New context-window or prompt features cannot be confidently estimated until measured against real workloads. Hold Confidence at 0.5 until benchmarks land.

Kano Basics drift. A Delighter (auto-completion) can become a Basic in two release cycles. Re-classify the Basic set quarterly.

Cross-Reference

See modules/scoring-framework.md for the per-factor scales used in this skill, modules/tradeoff-dimensions.md for the quality axes applied after prioritization, and plugins/leyline/skills/evaluation-framework/modules/multi-metric-evaluation-methodology.md for the math behind aggregation rules.

Research Enrichment

External evidence from the tome plugin adjusts feature-review scoring factors. Research findings produce deltas applied to initial human assessments, not replacement scores.

Channel-to-Factor Mapping

Each tome research channel maps to primary and secondary scoring factors:

Score Delta Calculation

Research findings produce an adjustment delta for each factor:

research_delta = findings_consensus * evidence_strength

Where:
  findings_consensus: -2 to +2 (direction and magnitude)
  evidence_strength: 0.0 to 1.0 (how reliable the findings are)

applied_delta = research_delta * channel_weight

If abs(applied_delta) < evidence_threshold:
    applied_delta = 0  (insufficient evidence, discard)

Channel Weight

The channel weight reflects how directly a channel's findings map to its primary factor:

Evidence Strength Sources

Fibonacci Clamping

Adjusted scores must remain on the Fibonacci scale used by the scoring framework: [1, 2, 3, 5, 8, 13].

FIBONACCI = [1, 2, 3, 5, 8, 13]

def clamp_to_fibonacci(raw_score: float) -> int:
    """Clamp raw score to nearest Fibonacci value."""
    return min(FIBONACCI, key=lambda f: abs(f - raw_score))

Clamping Rules

1. Calculate raw_adjusted = initial_score + applied_delta 2. Clamp to nearest Fibonacci value 3. Result must differ from initial by at most max_delta Fibonacci steps 4. If the clamped result exceeds max_delta steps from initial, use the value max_delta steps away

Example (max_delta = 2 steps):

• Initial: 5, raw_adjusted: 7 -> clamp: 8 (1 step away) OK
• Initial: 3, raw_adjusted: 11 -> clamp: 8 (3 steps away)

exceeds max_delta -> use 13 (2 steps away from 3) Wait: 13 is 4 steps from 3. So use 8 (2 steps from 3). Correction: count Fibonacci index steps, not arithmetic.

Fibonacci indices: 1=0, 2=1, 3=2, 5=3, 8=4, 13=5

def max_delta_clamp(initial: int, target: int, max_steps: int = 2) -> int:
    initial_idx = FIBONACCI.index(initial)
    target_idx = FIBONACCI.index(target)
    if abs(target_idx - initial_idx) <= max_steps:
        return target
    direction = 1 if target_idx > initial_idx else -1
    return FIBONACCI[initial_idx + direction * max_steps]

Graceful Degradation

When the tome plugin is not installed or research fails:

1. Tome not installed: Print warning, skip Phase 4.5 entirely. Initial scores stand unchanged. 2. Individual channel fails: Continue with remaining channels. Only apply deltas from successful channels. 3. All channels fail: Equivalent to tome not installed. Log the failure, proceed with initial scores. 4. Timeout exceeded: Use whatever findings collected so far. Partial results are acceptable.

Detection Protocol

Check for tome availability:

1. Look for plugins/tome/ directory in the project 2. If not found, check for tome in the global plugin path 3. If neither found, activate graceful degradation

Integration with tome Skill Interfaces

Phase 4.5 dispatches research via tome's public skill interfaces:

The feature-review skill invokes these via Skill() calls, not direct Python imports. This maintains loose coupling.

Research Topic Construction

For each feature under review, construct research topics:

topic = f"{feature_name} {feature_category} plugin/tool"

Example: "auto-save drafts developer tool" or "token optimization LLM CLI"

Synthesis Integration

After tome returns findings, extract deltas:

1. Parse synthesized report for quantitative signals (star counts, mention counts, citation counts) 2. Map quantitative signals to delta values using the channel-to-factor table 3. Extract qualitative signals (sentiment, novelty) for secondary factor adjustments 4. Apply delta calculation formula 5. Clamp to Fibonacci scale with max_delta constraint

Output Enhancement

When research enrichment runs, add to the feature inventory:

## Research Evidence

### Code Search (GitHub)
- Found 12 similar implementations, avg 340 stars
- **Reach adjustment**: +1 (broad ecosystem adoption)

### Discourse (HN/Reddit)
- 47 mentions in last 90 days, 78% positive sentiment
- **Impact adjustment**: +1 (strong community demand)

### Score Adjustments

| Feature | Factor | Initial | Delta | Adjusted | Evidence |
|---------|--------|---------|-------|----------|----------|
| Auth    | Reach  | 5       | +1    | 8        | 3 sources |
| Auth    | Impact | 3       | 0     | 3        | Low      |

Scoring Framework

Hybrid prioritization combining RICE (Intercom), WSJF (SAFe), and Kano classification, grounded in Multi-Criteria Decision Analysis (MCDA) principles.

Mathematical Foundation

This framework extends standard prioritization models with MCDA best practices:

• Normalization: Logarithmic normalization for score scales (handles non-linear value perception)
• Weighting: Customizable weights with validation requirements
• Trade-offs: Explicit handling through Value/Cost ratio
• Uncertainty: Confidence factor adjusts for estimation risk
• Sensitivity: Weight variations tested for robustness

Documentation: See Multi-Metric Evaluation Methodology for theoretical foundations.

The Formula

Feature Score = (Value Score / Cost Score) * Confidence

Where:
  Value Score = weighted_avg(Reach, Impact, Business Value, Time Criticality)
  Cost Score = weighted_avg(Effort, Risk, Complexity)
  Confidence = 0.0 to 1.0 (how certain are we about estimates?)

Validation Requirements

Before using this framework:

validation:
  weights:
    - Document weight derivation method (AHP, expert judgment, empirical)
    - Verify weights sum to 1.0 within each category (value, cost)
    - Test sensitivity to ±20% weight variations
    - Flag critical weights that significantly change rankings

  normalization:
    - Method: "logarithmic" (handles non-linear perception)
    - Rationale: "Diminishing returns on raw scores"
    - Scale_invariance: "Not required (absolute scale used)"

  uncertainty:
    - Confidence < 0.5: Require research before commitment
    - Document basis for confidence assessment
    - Consider worst-case scenario for low-confidence items

Value Factors

Reach (R)

Question: How many users/use-cases does this affect?

Impact (I)

Question: How much does this improve the user experience?

Business Value (BV)

Question: How does this contribute to business goals/OKRs?

Time Criticality (TC)

Question: What's the cost of delay?

Cost Factors

Effort (E)

Question: How much work is this?

Risk (Rk)

Question: What could go wrong?

Complexity (Cx)

Question: How hard is this to build correctly?

Confidence Scoring

Rate your confidence in the estimates:

Guardrail: Features with confidence < 0.5 should be flagged for research before commitment.

Kano Classification

After scoring, classify the feature:

Basic (Must-Have)

• Users expect this; absence causes dissatisfaction
• Doesn't increase satisfaction when present
• Action: validate these exist before anything else

Performance (Linear)

• More is better; satisfaction scales with quality
• Competitive differentiator
• Action: Optimize based on ROI

Delighters (Wow Factors)

• Unexpected features that create joy
• Absence doesn't hurt; presence delights
• Action: Build after basics and key performers

Indifferent

• Users don't care either way
• Action: Deprioritize or cut

Reverse

• Feature that some users actively dislike
• Action: Make optional or remove

Calculation Example

Feature: Auto-save drafts

# Value Factors
Reach: 8          # Most users write drafts
Impact: 5         # Significant UX improvement
Business Value: 3 # Supports retention KR
Time Criticality: 3 # Should do this quarter

Value Score = (8 + 5 + 3 + 3) / 4 = 4.75

# Cost Factors
Effort: 3         # 3-5 days
Risk: 2           # Low risk, understood problem
Complexity: 3     # Moderate, needs state management

Cost Score = (3 + 2 + 3) / 3 = 2.67

# Confidence
Confidence: 0.8   # Similar features built before

# Final Score
Feature Score = (4.75 / 2.67) * 0.8 = 1.42

# Classification
Kano: Performance (more saving = better UX)
Priority: Medium (1.42 is between 1.5-2.5 threshold)

Interpreting Scores

Custom Weights

Default weights can be customized in .feature-review.yaml:

weights:
  value:
    reach: 0.25           # Equal weighting
    impact: 0.30          # Slightly favor user impact
    business_value: 0.25  # Equal to reach
    time_criticality: 0.20 # Slightly less weight
  cost:
    effort: 0.40          # Effort matters most
    risk: 0.30            # Risk is significant
    complexity: 0.30      # Complexity matters

# REQUIRED: Document weight derivation
derivation:
  method: "expert_judgment"  # or "AHP" or "empirical"
  experts: 3
  date: "2025-01-07"
  rationale: "Impact weighted slightly higher based on user feedback"

Guardrails:

• Weights within each category must sum to 1.0
• Document how weights were derived (not arbitrary)
• Run sensitivity analysis before finalizing
• Flag weights that cause ranking instability

Comparison with Pure RICE

Feature Review extends RICE with WSJF's time criticality and business value, plus Kano classification for strategic context, all grounded in MCDA best practices.

Sensitivity Analysis

Before committing to prioritization, test robustness:

def priority_sensitivity_analysis(features, weights, variation=0.20):
    """
    Tests if rankings are stable to weight variations.

    Args:
        features: List of features with scores
        weights: Current weight configuration
        variation: Test ±20% changes

    Returns:
        Dict with sensitivity metrics
    """
    base_ranking = rank_features(features, weights)
    sensitivity = {}

    for category in ["value", "cost"]:
        for factor in weights[category].keys():
            # Test weight increase
            weights_plus = adjust_weight(weights, factor, +variation)
            ranking_plus = rank_features(features, weights_plus)
            correlation_plus = spearman_correlation(base_ranking, ranking_plus)

            # Test weight decrease
            weights_minus = adjust_weight(weights, factor, -variation)
            ranking_minus = rank_features(features, weights_minus)
            correlation_minus = spearman_correlation(base_ranking, ranking_minus)

            sensitivity[factor] = {
                "avg_correlation": (correlation_plus + correlation_minus) / 2,
                "sensitive": correlation_plus < 0.8 or correlation_minus < 0.8
            }

    return sensitivity

Interpretation:

• Correlation > 0.9: Ranking stable to this weight variation
• Correlation 0.8-0.9: Moderately sensitive
• Correlation < 0.8: Highly sensitive, weight is critical

Tradeoff Dimensions

Quality attributes for evaluating features. Based on ISO 25010 software quality model, CAP/PACELC theorems, and practical engineering concerns.

Overview

Every feature makes tradeoffs. This module provides structured evaluation across nine dimensions, each with specific criteria and scoring guidance.

Scoring Scale: 1-5 for each dimension

Dimension 1: Quality of Results

Question: Does the feature deliver correct, accurate results?

Evaluation Criteria

Considerations

• Correctness: Does it produce right answers?
• Completeness: Does it handle all expected inputs?
• Precision: How accurate are numerical/search results?
• Recall: Does it find everything it should?

Tradeoff Partners

• Quality often trades against Latency (more checks = slower)
• Quality often trades against Resource Usage (validation costs)

---

Dimension 2: Latency

Question: Does the feature meet timing requirements for its classification?

Evaluation Criteria by Type

For Reactive Features:

For Proactive Features:

Considerations

• P50 latency: Typical case
• P99 latency: Worst case (matters for reliability)
• Cold start: First invocation time
• Warm path: Subsequent invocations

Tradeoff Partners

• Latency trades against Quality (PACELC theorem)
• Latency trades against Consistency (eventual vs strong)

---

Dimension 3: Token Usage

Question: Is the feature context-efficient for LLM interactions?

Evaluation Criteria

Considerations

• Input tokens: How much context needed?
• Output tokens: How verbose are results?
• Caching potential: Can results be reused?
• Streaming: Can partial results reduce perception?

Measurement

Token Efficiency = Useful Output / Total Tokens

Target: > 0.5 for most features

Tradeoff Partners

• Token usage trades against Quality (more context = better results)
• Token usage trades against Readability (compression reduces clarity)

---

Dimension 4: Resource Usage (CPU/Memory)

Question: Is CPU and memory consumption reasonable?

Evaluation Criteria

Considerations

• Peak memory: Maximum allocation
• Sustained memory: Ongoing consumption
• CPU intensity: Processing load
• I/O patterns: Disk/network usage

Measurement Guidance

Tradeoff Partners

• Resources trade against Latency (caching uses memory)
• Resources trade against Scalability (per-user costs)

---

Dimension 5: Redundancy (Fault Tolerance)

Question: Does the feature handle failures gracefully?

Evaluation Criteria

Considerations

• Graceful degradation: Does it fail partially vs completely?
• Retry logic: Does it handle transient failures?
• Data durability: Is data protected from loss?
• Recovery time: How fast to recover?

CAP Theorem Implications

For distributed features:

• CP systems: May sacrifice availability for consistency
• AP systems: May sacrifice consistency for availability

Tradeoff Partners

• Redundancy trades against Complexity (more failure modes)
• Redundancy trades against Latency (replication delays)

---

Dimension 6: Readability (Maintainability)

Question: Can others understand and modify this feature?

Evaluation Criteria

Considerations

• Code clarity: Is logic obvious?
• Documentation: Are complex parts explained?
• Naming: Are variables/functions descriptive?
• Structure: Is code well-organized?

Measurement Proxies

• Cyclomatic complexity < 10
• Functions < 50 lines
• Clear separation of concerns
• Test coverage > 80%

Tradeoff Partners

• Readability trades against Token Usage (verbose = clearer)
• Readability trades against Resource Usage (abstractions have cost)

---

Dimension 7: Scalability

Question: Will the feature handle 10x load?

Evaluation Criteria

Considerations

• Horizontal scaling: Can add more instances?
• Vertical scaling: Can add more resources?
• Bottlenecks: Where does it fail first?
• State management: How is state distributed?

Scaling Patterns

Tradeoff Partners

• Scalability trades against Complexity (distributed systems are hard)
• Scalability trades against Redundancy (more nodes = more failure modes)

---

Dimension 8: Integration (Interoperability)

Question: Does the feature play well with existing systems?

Evaluation Criteria

Considerations

• API consistency: Matches existing patterns?
• Data formats: Uses standard formats?
• Dependencies: Minimal coupling?
• Extension points: Can be extended/wrapped?

Integration Checklist

• [ ] Uses project's standard data formats
• [ ] Follows naming conventions
• [ ] Integrates with existing logging/metrics
• [ ] Works with existing auth/permissions
• [ ] Compatible with existing tooling

Tradeoff Partners

• Integration trades against Innovation (conventions limit novelty)
• Integration trades against Optimization (generic > specialized)

---

Dimension 9: API Surface

Question: Is the API backward compatible and well-designed?

Evaluation Criteria

Considerations

• Breaking changes: How often do consumers break?
• Deprecation policy: Are changes communicated?
• Versioning: Is there a versioning strategy?
• Documentation: Is the contract clear?

API Design Checklist

• [ ] Additive changes only (no removal)
• [ ] Optional new fields with defaults
• [ ] Deprecation warnings before removal
• [ ] Semantic versioning
• [ ] Clear error contracts

Tradeoff Partners

• API stability trades against Innovation (can't change freely)
• API stability trades against Quality (may keep suboptimal designs)

---

Composite Scoring

Calculate overall tradeoff score:

Tradeoff Score = Σ(dimension_score * dimension_weight) / Σ(weights)

Default Weights

Guardrail

Minimum 5 dimensions must be evaluated. Cannot skip all tradeoff analysis.

---

Using Tradeoffs in Review

For Existing Features

1. Score each dimension 2. Identify dimensions below 3 3. Determine if improvement is feasible 4. Prioritize based on impact

For Proposed Features

1. Estimate scores for each dimension 2. Compare against existing features 3. Identify which tradeoffs are acceptable 4. Document accepted tradeoffs explicitly

Red Flag Combinations