Roadmap Advisor

"Strategic feature planning informed by codebase reality and industry best practices."

A comprehensive analysis skill that examines the CircleTel platform, identifies capability gaps against ISP industry standards, and generates prioritized, actionable roadmap recommendations with effort estimates and dependencies.

Philosophy: Not every feature needs building, but every significant gap needs surfacing. Engineering time is finite—prioritize improvements that maximize business value per hour invested.

When This Skill Activates

This skill automatically activates when you:

• •Need to plan the next development cycle or sprint
• •Want to identify missing features or capabilities
• •Compare CircleTel against industry standards
• •Prioritize technical improvements
• •Assess a specific domain (billing, customer experience, network, etc.)
• •Plan quarterly or annual product roadmaps
• •Evaluate build vs. buy decisions
• •Ask "what should we build next?"

Keywords: roadmap, feature planning, what should we build, gaps, priorities, audit, capability assessment, industry comparison, strategic planning, product roadmap, feature analysis, next sprint, improvements, recommendations

Commands

Available Domains

Core Analysis Methodology

Phase 1: Codebase Inventory (Automated)

Scan and categorize existing capabilities:

┌─────────────────────────────────────────────────────────────────┐
│                    CODEBASE INVENTORY                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  DATABASE ──► Count tables, analyze schema coverage              │
│      │        supabase/migrations/*.sql                          │
│      ▼                                                           │
│  API ROUTES ──► Categorize endpoints by domain                   │
│      │          app/api/**/*.ts                                  │
│      ▼                                                           │
│  SERVICES ──► Map service modules and capabilities               │
│      │        lib/*/*.ts                                         │
│      ▼                                                           │
│  COMPONENTS ──► Identify UI coverage per portal                  │
│      │          components/**/*.tsx                              │
│      ▼                                                           │
│  INTEGRATIONS ──► List external services and maturity            │
│                   lib/integrations/, webhooks/                   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Inventory Metrics:

• •Tables: Count by domain, schema completeness
• •API Routes: Endpoints per category, coverage gaps
• •Services: Business logic coverage, abstraction quality
• •Components: UI feature parity across portals (admin/customer/partner)
• •Integrations: Provider count, sync health, depth

Phase 2: Schema Analysis

Understand data model completeness:

1. •Extract table schemas from migrations
2. •Identify relationships and foreign keys
3. •Map tables to business domains using heuristics/domain-detection.md
4. •Flag orphaned or incomplete tables

Phase 3: Industry Benchmark Comparison

Compare against ISP standards using benchmarks/isp-industry-standard.md:

Status Legend:

• •✅ Complete - Full implementation
• •⚠️ Partial - Basic implementation, gaps remain
• •❌ Missing - No implementation

Phase 4: Gap Prioritization

For each identified gap, evaluate using rubrics in rubrics/:

Priority Score Formula:

PRIORITY = (Business × 0.4) + (Customer × 0.3) + (Enablement × 0.2) - (Complexity × 0.1)

Phase 5: Effort Estimation

Apply CircleTel-calibrated estimates from heuristics/effort-calibration.md:

Calibration Factor: Apply 1.2x to all estimates based on historical CircleTel data.

Phase 6: Dependency Mapping

Build dependency graph to ensure valid sequencing:

┌─────────────────────────────────────────────────────────────────┐
│                    DEPENDENCY EXAMPLE                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│    SLA Tracking ◄──── Uptime Monitoring                          │
│         │                   ▲                                    │
│         │                   │                                    │
│         ▼                   │                                    │
│    Auto Credits ◄──── Network Health DB ◄──── Provider API       │
│                                                                  │
│    (Can't build SLA without uptime, can't credit without SLA)   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Validate:

• • No circular dependencies
• • Prerequisites listed for each recommendation
• • Critical path identified

Phase 7: Roadmap Generation

Output structured recommendations following templates in templates/:

1. •Executive summary with maturity scorecard
2. •Priority tiers (Critical → High → Strategic)
3. •Quick wins (<1 week items)
4. •Dependency map
5. •Not Recommended section with reasoning

Output Format

See templates/full-audit-output.md for complete format. Key sections:

# CircleTel Roadmap Analysis

**Analysis Date**: YYYY-MM-DD
**Mode**: [Full Audit / Quick Scan / Domain: X]
**Codebase State**: X tables, Y routes, Z services

---

## Executive Summary

[2-3 paragraphs: key findings, top gaps, strategic recommendation]

### Maturity Scorecard

| Domain | Score | Industry Avg | Status |
|--------|-------|--------------|--------|
| Billing | 7/10 | 8/10 | ⚠️ Below |
| Customer | 8/10 | 7/10 | ✅ Above |
| Network | 3/10 | 8/10 | ❌ Critical |

---

## Priority 1: Critical Gaps (This Quarter)

### 1.1 [Feature Name]

**Current State**: [What exists today]
**Target State**: [Industry-standard capability]
**Business Impact**: X/10 | **Customer Impact**: Y/10
**Effort**: [Size] ([points], [weeks])
**Dependencies**: [Prerequisites]

**Implementation Approach**:
1. [Database work] (database-engineer)
2. [API work] (backend-engineer)
3. [UI work] (frontend-engineer)

---

## Quick Wins (This Week)

| Feature | Effort | Impact | Owner |
|---------|--------|--------|-------|
| [Item] | XS (1d) | Medium | [Role] |

---

## Not Recommended

| Feature | Reason |
|---------|--------|
| [Feature] | [Why not now] |

CircleTel-Specific Patterns

Strength Indicators (Don't Recommend Replacing)

• •Coverage system: 4-layer fallback (MTN WMS → Consumer → Provider → Mock)
• •Billing automation: NetCash Pay Now + eMandate + SMS (complete)
• •Three-context auth: Consumer/Partner/Admin separation
• •B2B KYC workflow: 7-stage pipeline (64% complete)
• •Admin panel: 36 sections, RBAC with 17 roles, 100+ permissions

Gap Indicators (Check First)

Look for missing tables/features in these areas:

• •Network monitoring: No network_health, uptime_logs, provider_status
• •SLA management: No sla_violations, service_credits
• •Usage tracking: Basic usage_history, no real-time or alerts
• •Churn: No churn_predictions, at_risk_customers
• •Knowledge base: No kb_articles, faq_categories

Load-Bearing Code (Be Conservative)

Require extra caution when recommendations touch:

• •lib/supabase/server.ts - All server-side DB access
• •lib/coverage/aggregation-service.ts - Revenue-critical coverage
• •components/providers/*AuthProvider.tsx - Auth state management
• •app/api/webhooks/**/*.ts - Payment and integration flows

Estimation Calibration

Use these CircleTel benchmarks for comparison:

RSI Integration

This skill integrates with the RSI (Recursive Self-Improvement) system:

Learning from Corrections

┌─────────────────────────────────────────────────────────────────┐
│                    RSI FEEDBACK LOOP                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  GENERATE ROADMAP ──► USER REVIEWS ──► CORRECTION?               │
│                                              │                   │
│                               NO            YES                  │
│                               │              │                   │
│                               ▼              ▼                   │
│                         SUCCESS         STORE CORRECTION         │
│                      (stats-tracker)   (compound-learnings)      │
│                                              │                   │
│                                              ▼                   │
│                                    UPDATE HEURISTICS             │
│                                    (extracted-rules/)            │
│                                              │                   │
│         IMPROVED FUTURE ◄─────────────────────┘                  │
│         RECOMMENDATIONS                                          │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Correction Types

When corrected, store the learning in:

• •corrections/roadmap/YYYY-MM-DD_description.md
• •Extract rules to extracted-rules/ for future runs

Stats Tracking

Track these metrics via stats-tracker:

• •Activation count per mode (full/quick/domain)
• •Recommendation acceptance rate
• •Correction rate
• •Most common domains analyzed
• •Average analysis duration

Validation Checklist

After generating a roadmap:

• • Codebase inventory matches reality (spot-check 3 items)
• • No recommendations for features that already exist
• • Dependencies form valid DAG (no cycles)
• • Effort estimates align with similar past work
• • Quick wins are genuinely quick (<2 days)
• • Critical items are genuinely critical (high business/customer impact)
• • Output follows template format
• • CircleTel-specific patterns considered
• • RSI corrections applied (if any exist in extracted-rules/)

Best Practices

1. •

   Verify Before Recommending: Always check docs/architecture/SYSTEM_OVERVIEW.md and Supabase tables before claiming something is missing

2. •

   Contextualize Effort: Reference similar completed work for calibration (check recent commits)

3. •

   Consider Constraints: Note regulatory (RICA, POPIA), resource, and technical constraints

4. •

   Balance Innovation vs Stability: Don't recommend changing load-bearing systems unless gap is critical

5. •

   Include Quick Wins: Every analysis should have 2-3 items achievable in <1 week

6. •

   Link to Specs: Reference existing Agent-OS specs in agent-os/specs/ when relevant

7. •

   Document Trade-offs: Explain why recommendation A over alternative B

8. •

   Update on Corrections: When corrected, store learning for future analyses

Related Skills

• •refactor - For code quality analysis within existing features
• •quality-gates - For evaluating output quality of specific documents
• •compound-learnings - For storing corrections and extracted rules
• •stats-tracker - For tracking skill effectiveness metrics
• •error-registry - For linking gaps to known recurring issues

Version: 1.0.0 Last Updated: 2026-02-12 Maintained By: CircleTel Engineering Based On: ISP Industry Best Practices + CircleTel Operational Knowledge