@esthernandez/vibe-doc 0.2.2 → 0.3.0

package/skills/guide/references/classification-taxonomy.md

@@ -0,0 +1,391 @@
+# Classification Taxonomy
+
+Reference for Vibe Doc agents. Defines the 8 primary categories and 5 deployment contexts.
+
+**Used by:** Scan skill (classification step), Generate skill (doc type selection).
+
+---
+
+## Primary Categories (8)
+
+### 1. Web Application
+
+**Definition:** Browser-based application with a frontend (React, Vue, Angular, etc.) and typically a backend service.
+
+**Signals:**
+- HTML/CSS/JavaScript assets in source tree
+- Framework files (package.json with react/vue/angular, frontend build config)
+- User authentication and sessions
+- Database or data persistence layer
+- API endpoints for frontend consumption
+
+**Examples:**
+- SaaS dashboards
+- Content platforms
+- Collaborative tools
+- Admin panels
+
+**Documentation focus:**
+- User flows and access patterns
+- API contracts (frontend ↔ backend)
+- Deployment architecture (CDN, load balancing, session management)
+- Security boundaries (auth, CORS, CSP)
+
+**Required doc types:**
+- Architecture Decision Records (decisions about tech stack, backend structure)
+- Runbook (deployment, rollback, scaling)
+- Threat Model (auth flows, data exposure, client-side vulnerabilities)
+- Test Plan (end-to-end scenarios, cross-browser)
+
+---
+
+### 2. API / Microservice
+
+**Definition:** Standalone service that exposes a programmatic interface (REST, GraphQL, gRPC, etc.), typically consumed by other services or client applications.
+
+**Signals:**
+- Route/endpoint definitions in code
+- API documentation files (OpenAPI/Swagger, GraphQL schema)
+- Request/response serialization (JSON, Protocol Buffers)
+- Service-to-service communication patterns
+- No frontend assets
+- Containerization (Dockerfile)
+
+**Examples:**
+- REST APIs
+- GraphQL servers
+- gRPC services
+- Webhook handlers
+- Internal microservices
+
+**Documentation focus:**
+- Interface contracts (input/output specs, error codes)
+- Deployment topology (scaling, service discovery, networking)
+- Integration with other services
+- Monitoring and alerting
+
+**Required doc types:**
+- API Specification (contract, versioning, error handling)
+- Architecture Decision Records (service boundaries, protocol choice)
+- Runbook (deployment, scaling, health checks)
+- Threat Model (authentication, input validation, service-to-service trust)
+
+---
+
+### 3. Data Pipeline
+
+**Definition:** ETL/ELT system that ingests, transforms, and outputs data. Can be batch (scheduled jobs) or streaming (continuous processing).
+
+**Signals:**
+- Job definitions (Airflow DAGs, Spark jobs, Cloud Functions with schedules)
+- Data transformation code (pandas, dbt, SQL, Spark transformations)
+- Scheduling configuration (cron, event triggers)
+- Data source/sink configurations (databases, data lakes, message queues)
+- Schema definitions or migrations
+
+**Examples:**
+- Analytics pipelines
+- Data warehouses (ELT into Snowflake, BigQuery, Redshift)
+- Real-time streaming (Kafka consumers, Dataflow)
+- Report generation jobs
+- ML training pipelines
+
+**Documentation focus:**
+- Data lineage and transformations
+- SLAs and failure handling
+- Data quality and validation
+- Scheduling and dependencies
+
+**Required doc types:**
+- Data Model Documentation (schemas, transformations, lineage)
+- Architecture Decision Records (orchestration tool choice, scheduling strategy)
+- Runbook (job execution, failure recovery, data backups)
+- Threat Model (data access controls, encryption, retention)
+
+---
+
+### 4. Infrastructure / Platform
+
+**Definition:** Systems software that manages compute, networking, storage, or development tooling. Typically consumed internally by other services.
+
+**Signals:**
+- Infrastructure-as-code (Terraform, CloudFormation, Helm, etc.)
+- Container orchestration (Kubernetes manifests, Docker Compose)
+- Monitoring and observability configurations (Prometheus, Datadog, etc.)
+- CLI or library interfaces
+- Configuration management (Ansible, Chef, Puppet, etc.)
+
+**Examples:**
+- Kubernetes operators
+- Database management platforms
+- Internal tooling platforms
+- CI/CD systems
+- Observability platforms
+
+**Documentation focus:**
+- Resource provisioning and management
+- High availability and disaster recovery
+- Capacity planning
+- Troubleshooting procedures
+
+**Required doc types:**
+- Architecture Decision Records (technology choices, design patterns)
+- Runbook (provisioning, troubleshooting, upgrades, disaster recovery)
+- Threat Model (access controls, privilege escalation, audit logging)
+- Deployment Procedure (infrastructure deployment, blue-green, rolling updates)
+
+---
+
+### 5. Mobile Application
+
+**Definition:** Native or cross-platform application running on mobile devices (iOS, Android).
+
+**Signals:**
+- Mobile framework files (Flutter, React Native, Swift, Kotlin, etc.)
+- App store configuration (App.json, AndroidManifest.xml, etc.)
+- Mobile-specific build processes
+- Device permissions and capabilities usage
+- Local data storage (SQLite, Realm, etc.)
+
+**Examples:**
+- Native iOS/Android apps
+- Cross-platform apps (Flutter, React Native)
+- Mobile-first web apps (PWAs)
+
+**Documentation focus:**
+- User onboarding and permissions flows
+- Local vs. remote data synchronization
+- Offline capabilities
+- Platform-specific APIs (camera, location, etc.)
+
+**Required doc types:**
+- Architecture Decision Records (framework choice, offline strategy)
+- Runbook (deployment to app stores, beta testing, hot patching)
+- Threat Model (local data storage, network security, permissions)
+- Test Plan (device compatibility, orientation, battery/memory constraints)
+
+---
+
+### 6. AI / ML System
+
+**Definition:** Systems that train, serve, or continuously learn from data. Includes LLMs, recommendation engines, classifiers, etc.
+
+**Signals:**
+- Training code (TensorFlow, PyTorch, scikit-learn, etc.)
+- Model files or checkpoints
+- Feature engineering or preprocessing code
+- Serving frameworks (TorchServe, TensorFlow Serving, HuggingFace, etc.)
+- Experiment tracking (MLflow, Weights & Biases, etc.)
+- Data versioning (DVC, Pachyderm, etc.)
+
+**Examples:**
+- LLM-powered applications
+- Recommendation systems
+- Computer vision systems
+- NLP services
+- Anomaly detection
+
+**Documentation focus:**
+- Model architecture and training process
+- Data dependencies and quality requirements
+- Performance metrics and SLOs
+- Bias and fairness considerations
+- Retraining frequency and triggers
+
+**Required doc types:**
+- Architecture Decision Records (framework, training strategy, serving approach)
+- Data Model Documentation (features, data sources, versioning)
+- Runbook (training procedures, model deployment, monitoring for drift)
+- Threat Model (data poisoning, model extraction, adversarial inputs)
+
+---
+
+### 7. Integration / Connector
+
+**Definition:** Glue code that connects external systems, APIs, or services together. Typically smaller, focused on data movement or event routing.
+
+**Signals:**
+- Third-party API client libraries
+- Webhook handlers or event listeners
+- Data transformation between system formats
+- Minimal business logic (mostly mapping and routing)
+- Scheduled sync jobs or event processors
+
+**Examples:**
+- Zapier-like automations
+- Data sync connectors (Segment, Fivetran, etc.)
+- Webhook bridges
+- Payment processor integrations
+- CRM sync tools
+
+**Documentation focus:**
+- External system contracts and APIs
+- Error handling and retry logic
+- Data transformations and mapping
+- Authentication with external systems
+
+**Required doc types:**
+- API Specification (external system contracts being integrated)
+- Architecture Decision Records (routing logic, error handling)
+- Runbook (monitoring external service health, debugging sync failures)
+- Threat Model (credential management, data in transit, third-party trust)
+
+---
+
+### 8. Claude Code Plugin
+
+**Definition:** A Claude Code plugin or plugin marketplace — distributed to users rather than deployed to production infrastructure. Composed of skill files, slash command definitions, and an optional CLI. Runs inside a coding agent, not on a server.
+
+**Signals:**
+- `.claude-plugin/plugin.json` manifest (strongest signal — overrides any incidental web-framework signals)
+- `.claude-plugin/marketplace.json` for multi-plugin repos
+- `skills/<skill-name>/SKILL.md` files defining agent behaviors
+- `commands/<command>.md` files defining slash commands
+- A CLI entry point (`bin` field in `package.json`) distributed via npm, frequently scoped
+- No runtime deployment target — the "deployment" is a user installing the plugin
+
+**Examples:**
+- `@esthernandez/app-project-readiness` — spec-driven development plugin
+- `@esthernandez/vibe-doc` — documentation gap analyzer plugin
+- Claude Code marketplace entries
+
+**Documentation focus:**
+- What the plugin does and who it's for (README)
+- How a user installs it (install guide, multiple paths: npm, marketplace, local)
+- What skills and slash commands it exposes (skill/command reference)
+- How users can contribute or track changes (changelog + contributing)
+
+**Required doc types:**
+- README (what-it-is, install, quick example, license)
+- Install Guide (prerequisites, install paths, verification, troubleshooting)
+- Skill/Command Reference (per-skill + per-command reference with examples)
+
+**Recommended doc types:**
+- Architecture Decision Records (why the plugin is structured the way it is)
+- Changelog + Contributing (Keep-a-Changelog + contributor onboarding)
+- Test Plan (if the plugin has meaningful behavior to verify)
+
+**Optional (not typically needed):**
+- Runbook, API Specification, Deployment Procedure, Threat Model, Data Model — these are for systems with runtime/deployment/data concerns. Elevate to Recommended or Required only if the plugin reads/writes local files, stores user data, or has a non-trivial security surface (e.g., memory persistence, network calls to external services).
+
+**Notes:**
+- Plugins bundle neither a server nor a database, so traditional ops docs don't apply.
+- The Skill/Command Reference is the plugin equivalent of an API spec — it's how users understand the interface they're consuming.
+- If a plugin persists data (e.g., a user profile at `~/.claude/profiles/builder.json`), the Threat Model becomes Recommended: document what's stored, where, and how users can inspect/delete it.
+
+---
+
+## Deployment Contexts (5)
+
+Modifiers that adjust Required/Recommended tiers for doc types.
+
+### 1. Regulated
+
+**Definition:** Subject to external compliance frameworks (legal, financial, healthcare, security standards).
+
+**Frameworks include:**
+- HIPAA (healthcare data)
+- PCI-DSS (payment card data)
+- SOC 2 (security and availability)
+- GDPR (EU data privacy)
+- FedRAMP (US government)
+- NIST Cybersecurity Framework
+- ISO 27001 (information security)
+
+**Impact:** Elevates all security and operational docs to Required. Threat Model becomes critical. Audit logging and data residency must be documented.
+
+**Required doc additions:**
+- Threat Model (mandatory if not already Required)
+- Deployment Procedure (must document compliance controls)
+- Data Model Documentation (must include retention and residency)
+
+---
+
+### 2. Customer-Facing
+
+**Definition:** Used directly by external customers (not internal-only).
+
+**Characteristics:**
+- User authentication and session management
+- User-visible SLAs and uptime requirements
+- Customer support procedures
+- Data isolation between customers (if multi-tenant)
+
+**Impact:** Elevates Runbook and Test Plan to Required. API Specification becomes critical if consumed by customer integrations.
+
+**Required doc additions:**
+- Runbook (must include SLA targets, escalation procedures)
+- Test Plan (customer-impacting scenarios, regression testing)
+- API Specification (if customers call APIs)
+
+---
+
+### 3. Internal Tooling
+
+**Definition:** Used only by the organization's own team (employees, contractors).
+
+**Characteristics:**
+- Typically higher tolerance for downtime
+- Feature velocity prioritized over stability
+- Internal security (network perimeter, employee vetting)
+- Changes can be communicated via Slack/email
+
+**Impact:** Lowers recommended docs to optional. Threat Model less critical (internal attack surface smaller). Runbook can focus on rapid recovery.
+
+**Effect:**
+- Optional docs may stay optional (Changelog, Contributing Guide)
+- Runbook emphasizes quick fixes over prevention
+
+---
+
+### 4. Multi-Tenant
+
+**Definition:** Single deployment serves multiple customers/organizations with data isolation.
+
+**Characteristics:**
+- Tenant isolation strategies (row-level security, schema per tenant, etc.)
+- Resource quotas and fair usage limits
+- Billing and metering logic
+- Account management and provisioning
+
+**Impact:** Adds Data Model Documentation to Required. Threat Model must include tenant isolation analysis.
+
+**Required doc additions:**
+- Data Model Documentation (isolation strategy, schema design)
+- Threat Model (tenant escape scenarios, data leakage)
+- API Specification (tenant context, authorization scopes)
+
+---
+
+### 5. Edge / Embedded
+
+**Definition:** Runs on edge devices, embedded systems, or has severe resource constraints (CPU, memory, network).
+
+**Characteristics:**
+- Device-specific constraints (ARM architecture, low memory, intermittent connectivity)
+- Firmware or binary deployments
+- Over-the-air (OTA) update mechanisms
+- Offline-first design
+
+**Impact:** Elevates Deployment Procedure and Runbook to Required. Test Plan must cover resource-constrained scenarios.
+
+**Required doc additions:**
+- Deployment Procedure (OTA process, version management, rollback on devices)
+- Runbook (recovery from resource exhaustion, network disconnects)
+- Test Plan (performance under constraints, battery/memory profiling)
+
+---
+
+## Classification Resolution
+
+When artifacts show mixed signals, resolve by asking:
+
+1. **What is the primary deployment target?** (Web, API, data system, etc.)
+2. **Who are the primary users?** (Customers, internal, public, etc.)
+3. **What's the biggest operational risk?** (Uptime, data loss, security breach, etc.)
+
+The answer to question 1 determines primary category. Questions 2-3 determine deployment contexts.
+
+---
+
+**Last updated:** 2026-04-15 | **Reference version:** 1.1

package/skills/guide/references/documentation-matrix.md

@@ -0,0 +1,297 @@
+# Documentation Matrix
+
+Reference for agents. Maps (Primary Category × Deployment Context) to doc type tiers (Required/Recommended/Optional).
+
+**Used by:** Scan skill (to determine gaps), Generate skill (to select doc types).
+
+---
+
+## Ops-Focused Matrix (8×7)
+
+Primary Categories × the original 7 operational document types. Base tier before deployment context modifiers.
+
+| Category                    | Threat Model | ADRs        | Runbook     | API Spec    | Deployment Proc | Test Plan   | Data Model  |
+| --------------------------- | ------------ | ----------- | ----------- | ----------- | --------------- | ----------- | ----------- |
+| **Web App**                 | Recommended  | Recommended | Required    | Required    | Required        | Recommended | Required    |
+| **API/Microservice**        | Required     | Recommended | Required    | Required    | Required        | Recommended | Recommended |
+| **Data Pipeline**           | Recommended  | Recommended | Required    | Optional    | Required        | Required    | Required    |
+| **Infrastructure/Platform** | Recommended  | Recommended | Required    | Optional    | Required        | Recommended | Optional    |
+| **Mobile App**              | Required     | Recommended | Required    | Recommended | Required        | Required    | Recommended |
+| **AI/ML System**            | Required     | Recommended | Required    | Recommended | Required        | Required    | Required    |
+| **Integration/Connector**   | Recommended  | Recommended | Recommended | Required    | Recommended     | Recommended | Optional    |
+| **Claude Code Plugin**      | Optional     | Recommended | Optional    | Optional    | Optional        | Recommended | Optional    |
+
+*Note: Table values above reflect the `BASE_MATRIX` in `packages/vibe-doc/src/gap-analyzer/matrix.ts` — source of truth is the code, this table is the human-readable mirror.*
+
+## Plugin-Focused Matrix (8×4)
+
+The same 8 categories × 4 plugin-oriented document types introduced in v0.2.2. These cover the "what-is-this-tool and how-do-I-use-it" docs that matter for distributed plugins and CLIs.
+
+| Category                    | README      | Install Guide | Skill/Command Ref | Changelog/Contributing |
+| --------------------------- | ----------- | ------------- | ----------------- | ---------------------- |
+| **Web App**                 | Required    | Recommended   | Optional          | Recommended            |
+| **API/Microservice**        | Required    | Recommended   | Optional          | Recommended            |
+| **Data Pipeline**           | Required    | Recommended   | Optional          | Recommended            |
+| **Infrastructure/Platform** | Required    | Required      | Optional          | Recommended            |
+| **Mobile App**              | Required    | Required      | Optional          | Recommended            |
+| **AI/ML System**            | Required    | Recommended   | Optional          | Recommended            |
+| **Integration/Connector**   | Required    | Required      | Recommended       | Recommended            |
+| **Claude Code Plugin**      | Required    | Required      | Required          | Recommended            |
+
+---
+
+## Deployment Context Modifiers
+
+### Regulated (HIPAA, PCI-DSS, SOC 2, GDPR, FedRAMP, NIST, ISO 27001)
+
+**Effect:** Elevates all docs one tier (Required → stays Required; Recommended → Required; Optional → Recommended).
+
+**Special additions:**
+- Threat Model becomes Required (if not already)
+- Deployment Procedure must document compliance controls
+- Data Model must include retention and data residency
+
+**Examples:**
+- Web App + Regulated: Threat Model (R), ADRs (R), Runbook (R), API Spec (R), Deployment Proc (R), Test Plan (Rec), Data Model (Rec)
+
+---
+
+### Customer-Facing
+
+**Effect:** Elevates User-visible docs (Runbook, Test Plan, API Spec if customers integrate).
+
+**Special additions:**
+- Runbook becomes Required (SLAs, escalation must be documented)
+- Test Plan becomes Required (customer regression testing essential)
+- API Specification becomes Required (if customers call APIs)
+
+**Examples:**
+- Web App + Customer-Facing: Threat Model (R), ADRs (R), Runbook (R), API Spec (Rec→R if exposed), Deployment Proc (Rec), Test Plan (Rec→R), Data Model (Rec)
+
+---
+
+### Internal Tooling
+
+**Effect:** Lowers non-critical docs. Runbook can focus on rapid recovery vs. prevention.
+
+**Special additions:**
+- Optional docs may stay optional (lower urgency on Changelog, Contributing)
+- Threat Model may downgrade to Recommended (internal attack surface smaller)
+
+**Examples:**
+- Data Pipeline + Internal: Threat Model (Rec), ADRs (R), Runbook (R), API Spec (Opt), Deployment Proc (Rec), Test Plan (Rec), Data Model (R)
+
+---
+
+### Multi-Tenant
+
+**Effect:** Makes Data Model and API Spec Required (isolation strategy must be clear).
+
+**Special additions:**
+- Data Model Documentation becomes Required
+- API Specification becomes Required (tenant context, authorization scopes)
+- Threat Model must include tenant isolation analysis
+
+**Examples:**
+- Web App + Multi-Tenant: Threat Model (R), ADRs (R), Runbook (R), API Spec (Rec→R), Deployment Proc (Rec), Test Plan (Rec), Data Model (Rec→R)
+
+---
+
+### Edge / Embedded
+
+**Effect:** Elevates deployment and testing docs.
+
+**Special additions:**
+- Deployment Procedure becomes Required (OTA, version mgmt, device rollback)
+- Runbook becomes Required (resource exhaustion, connectivity issues)
+- Test Plan becomes Required (performance under constraints)
+
+**Examples:**
+- Mobile App + Edge: Threat Model (Rec), ADRs (R), Runbook (Rec→R), API Spec (Rec), Deployment Proc (Rec→R), Test Plan (Rec→R), Data Model (Rec)
+
+---
+
+## Applied Examples
+
+### Example 1: Web App + Regulated (HIPAA) + Customer-Facing
+
+**Base (Web App):**
+- Threat Model: Required
+- ADRs: Required
+- Runbook: Required
+- API Spec: Recommended
+- Deployment Proc: Recommended
+- Test Plan: Recommended
+- Data Model: Recommended
+
+**Apply Regulated modifier:**
+- Everything Recommended → Required
+- Threat Model (stays Required)
+- Result: Threat Model (R), ADRs (R), Runbook (R), API Spec (R), Deployment Proc (R), Test Plan (R), Data Model (R)
+
+**Apply Customer-Facing modifier:**
+- Runbook (stays Required)
+- Test Plan (stays Required)
+- API Spec (stays Required)
+- Result: All 7 docs are Required
+
+---
+
+### Example 2: Data Pipeline + Internal Tooling
+
+**Base (Data Pipeline):**
+- Threat Model: Recommended
+- ADRs: Required
+- Runbook: Required
+- API Spec: Optional
+- Deployment Proc: Recommended
+- Test Plan: Recommended
+- Data Model: Required
+
+**Apply Internal Tooling modifier:**
+- Threat Model: Recommended (downgrades to Optional for truly internal)
+- Rest stay the same
+- Result: Threat Model (Opt), ADRs (R), Runbook (R), API Spec (Opt), Deployment Proc (Rec), Test Plan (Rec), Data Model (R)
+
+---
+
+### Example 3: API/Microservice + Multi-Tenant
+
+**Base (API/Microservice):**
+- Threat Model: Required
+- ADRs: Required
+- Runbook: Required
+- API Spec: Required
+- Deployment Proc: Recommended
+- Test Plan: Recommended
+- Data Model: Recommended
+
+**Apply Multi-Tenant modifier:**
+- Data Model: Recommended → Required
+- API Spec: Required (stays required, now must include tenant context)
+- Threat Model: Required (must include isolation analysis)
+- Result: Threat Model (R), ADRs (R), Runbook (R), API Spec (R), Deployment Proc (Rec), Test Plan (Rec), Data Model (R)
+
+---
+
+### Example 4: Mobile App + Edge + Customer-Facing
+
+**Base (Mobile App):**
+- Threat Model: Recommended
+- ADRs: Required
+- Runbook: Recommended
+- API Spec: Recommended
+- Deployment Proc: Required
+- Test Plan: Required
+- Data Model: Recommended
+
+**Apply Edge modifier:**
+- Deployment Proc: Required (stays required, OTA focus)
+- Runbook: Recommended → Required (device recovery, offline handling)
+- Test Plan: Required (stays required, add resource constraints)
+
+**Apply Customer-Facing modifier:**
+- Runbook: Required (stays required)
+- Test Plan: Required (stays required)
+- API Spec: Recommended → Required (if customers integrate)
+
+**Final:** Threat Model (Rec), ADRs (R), Runbook (R), API Spec (R), Deployment Proc (R), Test Plan (R), Data Model (Rec)
+
+---
+
+### Example 5: Claude Code Plugin (no modifiers)
+
+**Base (Claude Code Plugin):**
+- README: Required
+- Install Guide: Required
+- Skill/Command Reference: Required
+- ADRs: Recommended
+- Test Plan: Recommended
+- Changelog/Contributing: Recommended
+- Threat Model: Optional
+- Runbook: Optional
+- API Spec: Optional
+- Deployment Proc: Optional
+- Data Model: Optional
+
+**Why this rubric:** Plugins are distributed to users, not deployed to runtime infrastructure. The traditional ops docs (runbook, deployment procedure, data model) don't apply unless the plugin persists data or has a meaningful runtime surface. Instead, what matters is "what does this plugin do, how do I install it, and what commands does it expose" — hence README, Install Guide, and Skill/Command Reference as the three Required docs.
+
+**If the plugin persists user data** (e.g., `~/.claude/profiles/builder.json`), elevate Threat Model to Recommended and document what's stored, where, and how users can inspect or delete it.
+
+**Final:** README (R), Install Guide (R), Skill/Command Reference (R), ADRs (Rec), Test Plan (Rec), Changelog/Contributing (Rec), everything else (Opt).
+
+---
+
+## Tier Definitions
+
+### Required (Deployment Blocker)
+
+Must exist and be current before production deployment. Missing or stale Required docs block the `vibe-doc check` command.
+
+**Characteristics:**
+- Essential for safe operations
+- Directly impacts security, reliability, or compliance
+- Must be reviewed before deployment decision
+
+### Recommended (Should Do)
+
+Should exist before production, but not a hard blocker. Helpful for operations, support, and future maintenance.
+
+**Characteristics:**
+- Valuable for ongoing operations
+- Helps with debugging, scaling, and knowledge transfer
+- Can be created shortly after deployment with a priority
+
+### Optional (Nice to Have)
+
+Lower priority. Good to have but not essential for initial deployment. Often created after the system is stable.
+
+**Characteristics:**
+- Community-focused (Contributing Guide)
+- Long-term knowledge (Changelog, Benchmarks)
+- Can be added in retrospect without risk
+
+---
+
+## How Agents Use This Matrix
+
+**During Scan skill:**
+1. Determine primary category (Web App, API, etc.)
+2. Identify deployment contexts (Regulated? Customer-facing? Multi-tenant? Edge?)
+3. Look up base tiers from matrix
+4. Apply each deployment context modifier
+5. Calculate final Required/Recommended/Optional lists
+
+**During Generate skill:**
+1. Show user which gaps are Required vs. Recommended
+2. Suggest starting with Required tier
+3. Let user pick specific gaps to generate
+4. Pre-populate synthesis questions based on doc type
+
+**During Check skill:**
+1. Read classification from state
+2. Look up Required docs for that classification
+3. Check if Required docs exist and are current
+4. Return pass/fail based on Required tier only (Recommended/Optional ignored)
+
+---
+
+## Tier Override Pattern
+
+If user's situation doesn't match the matrix:
+
+```
+The matrix suggests Threat Model is Recommended for your stack.
+But given that you're handling customer payment data, I'm elevating 
+it to Required.
+
+Do you agree, or would you like to override?
+[agree] → Threat Model is Required
+[override] → Keep it as Recommended
+```
+
+Agents should respect user overrides. Document the override in state for future reference.
+
+---
+
+**Last updated:** 2026-04-15 | **Reference version:** 1.1