Skip to content

📊 Architectural Decision Log

This document records major architectural and strategic decisions for GetCimple. Each entry includes context, alternatives considered, decision made, and conditions for revisiting.

Decision Template

## YYYY-MM-DD: Decision Title

**Status**: Active/Superseded/Under Review
**Decision**: What we decided
**Context**: Why this decision was needed
**Alternatives Considered**:

- Option A: [description]
- Option B: [description]
  **Rationale**: Why we chose this approach
  **Consequences**: What this means for development
  **Review Trigger**: When to revisit this decision
  **Related Docs**: Links to relevant documentation

2025-10-13: E8 Audit Export vs Full Control Management

Status: Active Decision: Build audit export feature (152-control report from 40 questions) instead of full control management UI Context: Essential Eight assessment validated with 40 questions. Customers need audit artifacts but boards want simplicity. Must serve both without gold-plating.

Alternatives Considered:

  1. Do nothing: Keep 40-question assessment only

  2. Pro: No additional work required

  3. Con: Gap in audit support, customers need external artifacts

  4. Full 152-control management UI: Build control-level tracking, evidence workflows, status management

  5. Pro: Comprehensive control management in-platform

  6. Con: 1-2 dev cycles for 3-person team, serves 5% use case (audits) vs 95% (board decisions)
  7. Con: Turns GetCimple into GRC platform (not our market)

  8. Con: Premature optimization without validated demand

  9. Audit export (CHOSEN): One-button export generating 152-control report from 40 questions

  10. Pro: Serves audit needs with minimal complexity (1-2 days work)
  11. Pro: Validates demand before building full UI
  12. Pro: Maintains board experience simplicity
  13. Pro: Provides audit-ready artifact for external assessments

Rationale:

  • Boards need confidence from strategy-level summaries (8 strategies), not control checklists (152 controls)
  • Auditors need control-level artifacts, but this is a 5% use case vs 95% (board decisions)
  • Export approach serves both audiences: boards get simple UI, auditors get detailed report
  • Validates demand for control management before 1-2 cycle investment
  • Aligns with "calm productivity" and "no gold-plating" principles

Consequences:

  • ✅ Audit use case served with 1-2 days of work instead of 1-2 cycles
  • ✅ Board experience stays simple and fast (2-3 minutes)
  • ✅ Opportunity cost preserved - can build features for 95% use case
  • ✅ Validates demand for Phase 3 (full control management) before building
  • ⚠️ External audit workflow (export → send to auditor) vs in-platform
  • ⚠️ May need Phase 3 if customers demand real-time control management

Review Trigger:

  • > 50% of active customers using export feature monthly
  • > 3 paying customers requesting "manage this live in GetCimple"
  • Customers willing to pay for control management upgrade
  • Export becomes primary workflow (not secondary)

Related Docs:

  • ../06-features/e8-audit-export.md - Full export feature specification
  • ../06-features/essential-eight-mvp.md - Updated with export approach
  • ../00-documentation-meta/context-separation-guide.md - Building for boards principle

2025-10-13: No AI/Agents in MVP Architecture

Status: Active Decision: Build MVP with deterministic, rule-based processing (no AI agents) Context: Further simplification to get to market faster with 3-person team Alternatives Considered:

  • Single AI agent: More sophisticated but adds complexity and cost
  • Multi-agent system: Too complex for MVP Rationale: Sophistication should come from data structure and presentation, not AI. Can add AI post-MVP when we have revenue and data. Consequences: Simpler architecture, faster MVP delivery, no LLM costs, easier debugging Review Trigger: Customer demand for AI features + revenue to support infrastructure Related Docs: ../05-architecture/simplified-mvp-architecture.md

2025-01-11: Single Agent Architecture for MVP

Status: Superseded (replaced by "No AI/Agents in MVP" decision above) Decision: Build MVP with single AI agent handling all workflows Context: Need to balance sophistication with 3-person team reality Alternatives Considered:

  • Multi-agent system: More sophisticated but complex to build/maintain
  • No AI agents: Simpler but loses key differentiator Rationale: Anthropic's guidance + our resource constraints make single agent optimal for MVP Consequences: Simpler architecture, faster development, some latency on complex requests Review Trigger: When average latency > 2s or queue depth > 100 requests Related Docs: ../05-architecture/single-agent-mvp.md (Superseded - see agent-n8n-integration.md in vision)

2025-10-13: UQB Database Structure in MVP Scope

Status: Active Decision: Include UQB database structure and manual mappings in MVP, defer AI/ML features Context: UQB provides "answer once, use everywhere" value through data structure alone Alternatives Considered:

  • Include AI/ML inference in MVP: Powerful but overkill and adds complexity
  • Defer entire UQB to post-MVP: Simpler but loses key differentiation
  • Build UQB with manual mappings: Perfect balance of value and simplicity Rationale: 80% of value comes from simple database lookups and manual mappings, only 20% from AI/ML inference Consequences: MVP includes structured data and reuse logic, AI features deferred to post-MVP Review Trigger: After 50 customers actively using the system + question bank > 500 items Related Docs: ../05-architecture/unified-question-bank.md, ../05-architecture/e8-uqb-integration.md

2025-01-11: Unified Question Bank Architecture

Status: Superseded (clarified by "UQB Database Structure in MVP Scope" above) Decision: Build simple key-value store for questions, add intelligence later Context: Insurance forms have overlapping questions; users hate answering twice Alternatives Considered:

  • ML-powered inference engine: Powerful but overkill for MVP
  • No question reuse: Simpler but poor user experience Rationale: 80% value comes from basic reuse, 20% from intelligent inference Review Trigger: After 50 customers actively using the system Related Docs: ../05-architecture/unified-question-bank.md

2025-01-11: Framework Tags UI Strategy

Status: Active Decision: Use visual framework tags ([E8], [ACSC], [S180], [Privacy]) throughout UI Context: Users need to understand compliance coverage at a glance Alternatives Considered:

  • Text descriptions: More verbose, less scannable
  • Color coding only: Not accessible, less informative Rationale: Tags provide instant recognition and can trigger specific behaviors Consequences: Need consistent tag design system, user education Review Trigger: After user testing with 20+ customers Related Docs: ../07-design/framework-tags-design.md

2025-01-11: Documentation-First Development

Status: Active Decision: Create specs from internal docs before any implementation Context: Previous projects failed due to building without clear requirements Alternatives Considered:

  • Direct coding: Faster initially but leads to rework
  • Waterfall planning: Too rigid for startup Rationale: Specs provide clarity while maintaining agility Consequences: Slightly slower start but much less rework Review Trigger: After MVP launch, assess if process needs streamlining Related Docs: /specs/WORKFLOW.md

2025-01-11: MVP Feature Scope

Decision: Launch with 8 core features only Context: Need to get to market quickly with 3-person team Alternatives Considered:

  • Full-featured launch: Too ambitious for resources
  • Minimal 3-feature launch: Not enough value proposition Rationale: 8 features provide complete workflow while achievable in 8-12 weeks Consequences: Clear scope, some customer requests deferred to post-MVP Review Trigger: After initial customer feedback (first 10 customers) Related Docs: ../04-business/mvp-definition.md

Template for New Decisions

## 2025-MM-DD: [Decision Title]

**Status**: Active
**Decision**: [One sentence summary]
**Context**: [Why this decision was needed]
**Alternatives Considered**:

- [Option 1]: [Brief description]
- [Option 2]: [Brief description]
  **Rationale**: [Why we chose this approach]
  **Consequences**: [What this means for development]
  **Review Trigger**: [Specific metrics or conditions]
  **Related Docs**: [Links to relevant documentation]