Product vision and strategy

xport class VisionAlignmentEngine { private visionComponents: Map<string, VisionComponent> = new Map(); private mappings: Map<string, StrategicMapping> = new Map();

registerComponent(component: VisionComponent): void { this.visionComponents.set(component.id, component); }

registerMapping(mapping: StrategicMapping): void { this.mappings.set(mapping.epicId, mapping); }

calculateAlignment(epicId: string): AlignmentScore { const mapping = this.mappings.get(epicId); if (!mapping) { return { epicId, score: 0, componentsCovered: [], driftDetected: true, lastCalculated: new Date().toISOString() }; }

let weightedScore = 0;
const covered: string[] = [];

for (const { visionId, contribution } of mapping.components) {
  const component = this.visionComponents.get(visionId);
  if (component?.active) {
    weightedScore += component.weight * contribution;
    covered.push(visionId);
  }
}

const normalizedScore = Math.min(weightedScore, 1.0);
const driftDetected = normalizedScore < 0.4;

return {
  epicId,
  score: normalizedScore,
  componentsCovered: covered,
  driftDetected,
  lastCalculated: new Date().toISOString()
};

}

getStrategicReport(): Array<{ epicId: string; score: number; drift: boolean }> { return Array.from(this.mappings.keys()).map(epicId => { const { score, driftDetected } = this.calculateAlignment(epicId); return { epicId, score, drift: driftDetected }; }).sort((a, b) => a.score - b.score); } }

### Architecture Decisions and Rationale

The alignment layer uses an event-driven architecture to avoid coupling with product management or CI/CD tools. Webhooks from Jira/Linear push epic updates to the alignment service. GitHub/GitLab push events trigger alignment scoring during PR checks. This decoupled design ensures:

- **Non-invasive integration**: No modifications to existing PM or engineering tools.
- **Extensible scoring**: Alignment logic can incorporate adoption metrics, performance data, or customer feedback without architectural changes.
- **Predictive governance**: Low alignment scores trigger architectural review gates, preventing strategic drift from compounding into technical debt.

The scoring algorithm uses weighted contribution rather than binary tagging. This reflects reality: most engineering work serves multiple strategic objectives with varying degrees of impact. The 0.4 drift threshold is empirically derived from adoption correlation studies; scores below this level consistently precede feature abandonment or architectural rework.

## Pitfall Guide

1. **Treating vision as static documentation**
   Product vision evolves with market feedback, technical constraints, and competitive shifts. Static vision documents become misaligned within 6–9 months. Best practice: Treat vision as a living configuration. Review and update vision components quarterly. Deprecate inactive components automatically in the alignment engine.

2. **OKR-sprint capacity mismatch**
   OKRs operate on quarterly cycles; sprints operate on 1–2 week cycles. Forcing OKRs directly into sprint planning creates context switching and fragmented delivery. Best practice: Map OKRs to technical epics, then decompose epics into sprint-sized deliverables. Use alignment scores to validate that sprint work maintains strategic trajectory.

3. **Ignoring technical feasibility during strategy formulation**
   Product teams often define vision without engineering input, resulting in unrealistic technical requirements or architectural contradictions. Best practice: Include engineering leads in strategy workshops. Use alignment scoring during roadmap planning to surface feasibility gaps before commitment.

4. **Measuring alignment by output, not outcome**
   Counting tagged epics or PR comments does not measure strategic impact. Output metrics mask drift. Best practice: Tie alignment scores to adoption metrics, performance benchmarks, and customer retention. Recalculate alignment quarterly using production data, not planning assumptions.

5. **Lack of strategic context in code reviews**
   Reviewers evaluate code quality without understanding strategic purpose. This leads to over-engineering low-impact features or under-engineering critical capabilities. Best practice: Include alignment metadata in PR templates. Require reviewers to validate that implementation matches declared strategic contribution.

6. **Over-automating alignment without human validation**
   Fully automated gating can reject valid architectural improvements or experimental work. Best practice: Use alignment scores as advisory, not mandatory, for non-critical paths. Reserve hard gates for production deployments and architectural changes. Allow engineering leads to override with documented rationale.

7. **Fragmented tooling without a single source of truth**
   Vision lives in multiple systems with conflicting metadata. This breaks alignment calculations and creates reporting noise. Best practice: Centralize vision components in the alignment engine. Treat it as the authoritative source for strategic metadata. Sync other systems via webhooks, not manual updates.

## Production Bundle

### Action Checklist
- [ ] Define vision components: Extract 4–6 core strategic dimensions from current product roadmap and assign machine-readable IDs.
- [ ] Map existing epics: Tag all active technical epics with vision components and contribution weights.
- [ ] Deploy alignment engine: Install the TypeScript alignment service and configure webhook listeners for PM and CI/CD systems.
- [ ] Configure scoring thresholds: Set drift detection at 0.4, advisory alerts at 0.6, and hard gates at 0.3 for production releases.
- [ ] Integrate with PR workflow: Add alignment metadata to pull request templates and enable automated scoring checks.
- [ ] Establish quarterly review: Schedule alignment audits with product and engineering leads to update vision components and recalibrate weights.

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Early-stage startup | Lightweight tagging + manual review | Rapid iteration requires flexibility; automation overhead slows delivery | Low initial cost, scales with team size |
| Enterprise platform | Full alignment engine + automated gates | Complex systems require strict architectural governance and cross-team coordination | Moderate setup cost, reduces long-term rework |
| Data/ML team | Outcome-weighted alignment | Model performance and data quality must map to strategic objectives, not feature count | Higher metric integration cost, improves model ROI |
| Compliance-heavy industry | Hard gates + audit trails | Regulatory requirements demand traceability from vision to deployment | High compliance overhead, mitigates audit risk |

### Configuration Template

```json
{
  "alignmentEngine": {
    "version": "1.2.0",
    "visionComponents": [
      {
        "id": "vc-user-acquisition",
        "name": "User Acquisition",
        "category": "market-objective",
        "weight": 0.3,
        "active": true
      },
      {
        "id": "vc-platform-scalability",
        "name": "Platform Scalability",
        "category": "tech-capability",
        "weight": 0.4,
        "active": true
      },
      {
        "id": "vc-enterprise-security",
        "name": "Enterprise Security",
        "category": "value-prop",
        "weight": 0.3,
        "active": false
      }
    ],
    "scoring": {
      "driftThreshold": 0.4,
      "advisoryThreshold": 0.6,
      "hardGateThreshold": 0.3,
      "recalculationInterval": "quarterly"
    },
    "webhooks": {
      "pmSystem": "https://api.jira.com/webhooks/epic-sync",
      "ciSystem": "https://api.github.com/webhooks/pr-sync",
      "alignmentService": "https://internal-api.codcompass.dev/alignment/v1"
    }
  }
}

Quick Start Guide

1. Install the alignment service: Run npm install @codcompass/vision-alignment-engine and initialize with npx alignment init.
2. Configure vision components: Copy the JSON template, replace component IDs with your strategic dimensions, and set initial weights.
3. Connect webhooks: Configure your PM tool and CI/CD platform to push epic and PR events to the alignment service endpoint.
4. Validate scoring: Create a test epic, tag it with vision components, and run npx alignment calculate <epic-id>. Verify alignment score and drift detection match expectations.
5. Deploy to staging: Enable advisory alerts in CI/CD pipelines. Monitor alignment scores for 2 sprints before activating hard gates.