jumpstart-mode 1.1.13 → 1.1.14

package/.jumpstart/skills/postgresql-pgvector/templates/schema.rfp-retrieval.sql

@@ -0,0 +1,139 @@
+-- =============================================================================
+-- RFP Answer Retrieval Schema
+-- Stores prior RFP answers with embeddings for semantic retrieval, recency
+-- weighting, approval status filtering, and capability-area search.
+-- Requires: PostgreSQL 14+ with pgvector extension
+-- =============================================================================
+
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- ---------------------------------------------------------------------------
+-- Embedding model registry
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS embedding_models (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    provider        TEXT NOT NULL,
+    model_name      TEXT NOT NULL,
+    dimensions      INTEGER NOT NULL,
+    distance_metric TEXT NOT NULL DEFAULT 'cosine',
+    is_active       BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at      TIMESTAMPTZ DEFAULT now(),
+    UNIQUE (provider, model_name, dimensions)
+);
+
+-- ---------------------------------------------------------------------------
+-- RFP source documents
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS rfp_documents (
+    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    client_name         TEXT,
+    industry            TEXT,
+    rfp_title           TEXT NOT NULL,
+    rfp_due_date        DATE,
+    submission_date     DATE,
+    outcome             TEXT CHECK (outcome IN ('won', 'lost', 'no_bid', 'pending', 'unknown')),
+    source_uri          TEXT,
+    metadata            JSONB NOT NULL DEFAULT '{}',
+    created_at          TIMESTAMPTZ DEFAULT now()
+);
+
+-- ---------------------------------------------------------------------------
+-- Individual RFP questions and approved answers
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS rfp_answers (
+    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    rfp_document_id     UUID REFERENCES rfp_documents(id) ON DELETE SET NULL,
+    embedding_model_id  UUID NOT NULL REFERENCES embedding_models(id),
+    client_name         TEXT,
+    industry            TEXT,
+    capability_area     TEXT,       -- 'cloud_migration', 'ai_innovation', 'data_engineering', etc.
+    question            TEXT NOT NULL,
+    answer              TEXT NOT NULL,
+    answer_word_count   INTEGER,
+    rfp_due_date        DATE,
+    approval_status     TEXT NOT NULL DEFAULT 'draft'
+                        CHECK (approval_status IN ('draft', 'approved', 'archived', 'superseded')),
+    approved_by         TEXT,
+    approved_at         TIMESTAMPTZ,
+    superseded_by       UUID REFERENCES rfp_answers(id),
+    reuse_count         INTEGER NOT NULL DEFAULT 0,
+    last_used_at        TIMESTAMPTZ,
+    question_embedding  vector(1536),   -- embedding of the question text
+    answer_embedding    vector(1536),   -- embedding of the answer text (optional)
+    metadata            JSONB NOT NULL DEFAULT '{}',
+    is_deleted          BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at          TIMESTAMPTZ DEFAULT now(),
+    updated_at          TIMESTAMPTZ DEFAULT now()
+);
+
+-- ---------------------------------------------------------------------------
+-- Capability area taxonomy
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS capability_areas (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    slug        TEXT NOT NULL UNIQUE,   -- 'ai_innovation', 'cloud_native', etc.
+    label       TEXT NOT NULL,
+    description TEXT,
+    parent_id   UUID REFERENCES capability_areas(id),
+    is_active   BOOLEAN NOT NULL DEFAULT TRUE
+);
+
+-- ---------------------------------------------------------------------------
+-- Retrieval events for RFP answer lookups
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS rfp_retrieval_events (
+    id                      UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    trace_id                TEXT,
+    user_id                 TEXT,
+    query_text              TEXT NOT NULL,
+    capability_area         TEXT,
+    client_filter           TEXT,
+    industry_filter         TEXT,
+    recency_filter_days     INTEGER,
+    approval_filter         TEXT,
+    retrieved_answer_ids    UUID[],
+    scores                  JSONB,
+    top_k                   INTEGER,
+    latency_ms              INTEGER,
+    created_at              TIMESTAMPTZ DEFAULT now()
+);
+
+-- ---------------------------------------------------------------------------
+-- Indexes
+-- ---------------------------------------------------------------------------
+
+-- Vector search on question embedding (primary retrieval path)
+CREATE INDEX IF NOT EXISTS rfp_answers_question_embedding_hnsw_idx
+    ON rfp_answers
+    USING hnsw (question_embedding vector_cosine_ops)
+    WITH (m = 16, ef_construction = 64);
+
+-- Full-text search on question + answer text
+CREATE INDEX IF NOT EXISTS rfp_answers_fts_idx
+    ON rfp_answers
+    USING gin (to_tsvector('english', question || ' ' || answer));
+
+-- Approval status filter
+CREATE INDEX IF NOT EXISTS rfp_answers_approval_status_idx
+    ON rfp_answers (approval_status)
+    WHERE is_deleted = FALSE;
+
+-- Capability area filter
+CREATE INDEX IF NOT EXISTS rfp_answers_capability_area_idx
+    ON rfp_answers (capability_area)
+    WHERE is_deleted = FALSE;
+
+-- Recency filter
+CREATE INDEX IF NOT EXISTS rfp_answers_rfp_due_date_idx
+    ON rfp_answers (rfp_due_date DESC)
+    WHERE is_deleted = FALSE;
+
+-- Active answers only
+CREATE INDEX IF NOT EXISTS rfp_answers_active_approved_idx
+    ON rfp_answers (approval_status, rfp_due_date DESC)
+    WHERE is_deleted = FALSE AND approval_status = 'approved';
+
+-- JSONB metadata
+CREATE INDEX IF NOT EXISTS rfp_answers_metadata_gin_idx
+    ON rfp_answers
+    USING gin (metadata);

package/.jumpstart/skills/postgresql-pgvector/templates/sqlmodel_models.py

@@ -0,0 +1,207 @@
+"""
+SQLModel models for PostgreSQL pgvector RAG application.
+
+Key pattern: vector columns use sa_column=Column(Vector(n)) because SQLModel
+does not natively support the pgvector `vector` type.
+
+Usage:
+    from app.models import DocumentChunk, Document, EmbeddingModel
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Optional
+from uuid import UUID
+
+import sqlalchemy as sa
+from pgvector.sqlalchemy import Vector
+from sqlalchemy import Column
+from sqlmodel import Field, Relationship, SQLModel
+
+
+# =============================================================================
+# Embedding model registry
+# =============================================================================
+class EmbeddingModel(SQLModel, table=True):
+    __tablename__ = "embedding_models"
+
+    id: UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    provider: str
+    model_name: str
+    dimensions: int
+    distance_metric: str = Field(default="cosine")
+    is_active: bool = Field(default=True)
+    created_at: Optional[datetime] = Field(
+        default=None, sa_column=sa.Column(sa.TIMESTAMP(timezone=True), server_default=sa.text("now()"))
+    )
+
+    # Relationships
+    chunks: list["DocumentChunk"] = Relationship(back_populates="embedding_model")
+
+
+# =============================================================================
+# Source documents
+# =============================================================================
+class Document(SQLModel, table=True):
+    __tablename__ = "documents"
+
+    id: UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    source_system: str
+    source_uri: str = Field(unique=True)
+    title: Optional[str] = None
+    content_hash: Optional[str] = None
+    file_type: Optional[str] = None
+    page_count: Optional[int] = None
+    language: str = Field(default="en")
+    security_label: str = Field(default="internal")
+    metadata: dict = Field(default_factory=dict, sa_column=sa.Column(sa.JSON))
+    ingested_at: Optional[datetime] = Field(
+        default=None, sa_column=sa.Column(sa.TIMESTAMP(timezone=True))
+    )
+    is_deleted: bool = Field(default=False)
+    created_at: Optional[datetime] = Field(
+        default=None, sa_column=sa.Column(sa.TIMESTAMP(timezone=True), server_default=sa.text("now()"))
+    )
+    updated_at: Optional[datetime] = Field(
+        default=None, sa_column=sa.Column(sa.TIMESTAMP(timezone=True), server_default=sa.text("now()"))
+    )
+
+    # Relationships
+    chunks: list["DocumentChunk"] = Relationship(back_populates="document")
+
+
+# =============================================================================
+# Document chunks with vector embedding
+# =============================================================================
+class DocumentChunk(SQLModel, table=True):
+    __tablename__ = "document_chunks"
+
+    id: UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    document_id: UUID = Field(foreign_key="documents.id", index=True)
+    embedding_model_id: UUID = Field(foreign_key="embedding_models.id")
+    chunk_index: int
+    chunk_text: str
+    token_count: Optional[int] = None
+    chunk_strategy: str = Field(default="fixed")
+    chunk_version: int = Field(default=1)
+    metadata: dict = Field(default_factory=dict, sa_column=sa.Column(sa.JSON))
+    is_deleted: bool = Field(default=False)
+    created_at: Optional[datetime] = Field(
+        default=None, sa_column=sa.Column(sa.TIMESTAMP(timezone=True), server_default=sa.text("now()"))
+    )
+
+    # pgvector column — must use sa_column override, not a standard type annotation
+    embedding: Optional[list[float]] = Field(
+        default=None,
+        sa_column=Column(Vector(1536))  # change 1536 to match your embedding model
+    )
+
+    # Relationships
+    document: Optional[Document] = Relationship(back_populates="chunks")
+    embedding_model: Optional[EmbeddingModel] = Relationship(back_populates="chunks")
+    citations: list["ChunkCitation"] = Relationship(back_populates="chunk")
+
+
+# =============================================================================
+# Citation grounding
+# =============================================================================
+class ChunkCitation(SQLModel, table=True):
+    __tablename__ = "chunk_citations"
+
+    id: UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    chunk_id: UUID = Field(foreign_key="document_chunks.id", index=True)
+    source_uri: str
+    page_number: Optional[int] = None
+    section_heading: Optional[str] = None
+    start_char: Optional[int] = None
+    end_char: Optional[int] = None
+    citation_text: Optional[str] = None
+
+    # Relationships
+    chunk: Optional[DocumentChunk] = Relationship(back_populates="citations")
+
+
+# =============================================================================
+# Ingestion batch tracking
+# =============================================================================
+class IngestionBatch(SQLModel, table=True):
+    __tablename__ = "ingestion_batches"
+
+    id: UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    source_system: str
+    batch_label: Optional[str] = None
+    started_at: Optional[datetime] = Field(
+        default=None, sa_column=sa.Column(sa.TIMESTAMP(timezone=True), server_default=sa.text("now()"))
+    )
+    completed_at: Optional[datetime] = Field(
+        default=None, sa_column=sa.Column(sa.TIMESTAMP(timezone=True))
+    )
+    status: str = Field(default="running")
+    records_processed: int = Field(default=0)
+    records_failed: int = Field(default=0)
+    error_summary: Optional[str] = None
+    metadata: dict = Field(default_factory=dict, sa_column=sa.Column(sa.JSON))
+
+
+# =============================================================================
+# Retrieval events (observability)
+# =============================================================================
+class RetrievalEvent(SQLModel, table=True):
+    __tablename__ = "retrieval_events"
+
+    id: UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    trace_id: Optional[str] = Field(default=None, index=True)
+    session_id: Optional[str] = None
+    user_id: Optional[str] = None
+    query_text: str
+    query_embedding_model: Optional[str] = None
+    filters: dict = Field(default_factory=dict, sa_column=sa.Column(sa.JSON))
+    retrieved_chunk_ids: Optional[list[UUID]] = Field(
+        default=None, sa_column=sa.Column(sa.ARRAY(sa.UUID(as_uuid=True)))
+    )
+    scores: Optional[dict] = Field(default=None, sa_column=sa.Column(sa.JSON))
+    top_k: Optional[int] = None
+    latency_ms: Optional[int] = None
+    result_used: Optional[bool] = None
+    created_at: Optional[datetime] = Field(
+        default=None, sa_column=sa.Column(sa.TIMESTAMP(timezone=True), server_default=sa.text("now()"))
+    )
+
+
+# =============================================================================
+# Pydantic request/response schemas (not table=True)
+# =============================================================================
+class DocumentIngest(SQLModel):
+    source_system: str
+    source_uri: str
+    title: Optional[str] = None
+    file_type: Optional[str] = None
+    security_label: str = "internal"
+    metadata: dict = {}
+
+
+class ChunkIngest(SQLModel):
+    chunk_index: int
+    chunk_text: str
+    token_count: Optional[int] = None
+    chunk_strategy: str = "fixed"
+    metadata: dict = {}
+
+
+class SearchRequest(SQLModel):
+    query: str
+    top_k: int = 10
+    filters: dict = {}
+    include_citations: bool = False
+
+
+class SearchResult(SQLModel):
+    chunk_id: UUID
+    chunk_text: str
+    similarity: float
+    metadata: dict = {}
+    source_uri: Optional[str] = None
+    page_number: Optional[int] = None
+    section_heading: Optional[str] = None

package/.jumpstart/skills/pre-deployment-gotcha-review/README.md

@@ -0,0 +1,84 @@
+# Pre-Deployment Gotcha Review
+
+A skill for reviewing pre-deployment documents, proposals, architectures, and scopes to identify hidden gotchas, unknown unknowns, risky assumptions, and implementation traps before the team commits to build or deployment.
+
+## When to Use
+
+Use this skill when reviewing any document before estimation, SOW signature, sprint planning, or deployment:
+
+- ADRs, proposals, RFPs, SOWs, POCs, MVP scopes, PRDs
+- Architecture notes, solution diagrams, integration plans
+- RAG designs, agentic workflow designs, AI solution outlines
+- Workshop outputs, backlog items, technical assumptions
+
+## What It Produces
+
+A structured report with:
+- Executive summary and readiness rating
+- Gotcha heatmap across 10 review categories
+- Detailed findings with severity, citations, and mitigations
+- Unknown unknowns register
+- Assumption register
+- Owner-grouped clarifying questions
+- Prioritized mitigation backlog
+- Go / no-go recommendation
+
+## Review Categories
+
+1. Identity, Authentication, SSO, MFA
+2. Authorization and Access Control
+3. API Gateway and Integration
+4. Legacy On-Prem Data Access
+5. RAG Document Identity and ACL Preservation
+6. Data Readiness
+7. AI, Agent, and Model Risk
+8. Security, Compliance, and Legal
+9. Operational Readiness
+10. Delivery, Scope, and Commercial Risk
+
+## Folder Structure
+
+```
+pre-deployment-gotcha-review/
+├── SKILL.md                          # Core skill instructions
+├── README.md                         # This file
+├── evals/
+│   └── evals.json                    # Test cases for skill evaluation
+├── references/
+│   ├── gotcha-taxonomy.md            # Complete gotcha pattern taxonomy
+│   ├── review-methodology.md         # Review approach and interrogation patterns
+│   ├── identity-auth-mfa.md          # Identity/SSO/MFA deep dive
+│   ├── authorization-access-control.md
+│   ├── api-gateway-apigee.md         # API gateway and Apigee patterns
+│   ├── legacy-onprem-access.md       # On-prem and legacy system access
+│   ├── rag-document-identity-acl.md  # RAG OID and ACL preservation
+│   ├── ai-agent-risk.md              # AI/agent/model risk patterns
+│   ├── data-readiness.md             # Data quality and availability
+│   ├── security-compliance.md        # Security, compliance, legal
+│   ├── operational-readiness.md      # Operations and support
+│   ├── delivery-commercial-risk.md   # Scope, estimation, commercial
+│   └── mcp-extension-guide.md        # MCP/Context7 documentation lookup
+├── templates/
+│   ├── gotcha-review-report.md       # Full report template
+│   ├── unknown-unknowns-register.md  # Unknown unknowns format
+│   ├── assumption-register.md        # Assumption tracking format
+│   ├── clarifying-questions.md       # Owner-grouped questions
+│   ├── mitigation-backlog.md         # Prioritized mitigations
+│   ├── readiness-rating.md           # Rating rubric
+│   └── source-citation-matrix.md     # Citation traceability
+└── scripts/
+    ├── extract_document_claims.py    # Extract claims from source docs
+    ├── build_citation_matrix.py      # Build citation matrix from report
+    ├── classify_gotchas.py           # Classify claims against taxonomy
+    ├── generate_question_backlog.py  # Generate owner-grouped questions
+    └── validate_report_completeness.py # Validate report structure
+```
+
+## Related Skills
+
+- `risk-assumption-register` — Structures known risks into a register
+- `sow-proposal-reviewer` — Evaluates document quality and completeness
+- `scope-creep-detector` — Compares scope against discovery notes
+- `agent-governance` — Designs production controls for agents
+- `integration-surface-mapper` — Inventories systems and APIs
+- `data-readiness-assessor` — Scores data sources for AI fitness

package/.jumpstart/skills/pre-deployment-gotcha-review/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: pre-deployment-gotcha-review
+description: >-
+  Review ADRs, proposals, RFPs, SOWs, POCs, MVP scopes, PRDs, architecture notes, solution designs,
+  integration plans, RAG designs, agent workflow designs, backlog items, meeting transcripts, workshop
+  outputs, or any pre-deployment artifact to identify hidden gotchas, unknown unknowns, risky assumptions,
+  integration gaps, identity and access issues, data readiness concerns, AI and model risks,
+  security and compliance gaps, operational readiness gaps, delivery and commercial risks,
+  and any implementation traps before build, estimation, or deployment.
+  Use this skill whenever the user asks to review a document for risks, gotchas, hidden assumptions,
+  implementation traps, or production readiness — even when phrased as "what are we missing",
+  "what could go wrong", "step on the rake", "pre-deployment review", "review this SOW for gotchas",
+  "is this ready to build", "before we estimate", "unknown unknowns", "delivery risk review",
+  "integration risk", "RAG access control review", "hidden assumptions", or "what will bite us".
+  Covers all ten review categories including identity/auth/SSO/MFA, authorization, API gateways,
+  legacy on-prem access, RAG document ACL preservation, data readiness, AI/agent/model risk,
+  security/compliance/legal, operational readiness, and delivery/scope/commercial risk.
+  Common past roadblocks include Ping/MFA integration, Apigee gateway onboarding, on-prem network
+  line-of-sight, and RAG document OID/permission inheritance — but the review is not limited to these.
+---
+
+# Pre-Deployment Gotcha Review
+
+## Purpose
+
+Review pre-deployment documents and solution ideas before build, deployment, or fixed-scope commitment. Identify hidden risks, missing assumptions, ambiguous decisions, unknown unknowns, and implementation gotchas that could cause rework, delay, security issues, data exposure, failed integrations, or production-readiness gaps.
+
+This skill is intentionally skeptical and thorough. It exists to help the team avoid stepping on the rake after it is too late.
+
+## Positioning Within Jump Start and AI Innovation Pod
+
+This skill sits directly between ideation and delivery — where most AI project risk is created. Use it:
+
+- After a Jump Start workshop produces recommendations but before pricing or SOW language
+- Before a Pod delivery commits to fixed-scope or fixed-fee
+- When reviewing architecture notes before sprint planning
+- When a proposal references integrations, APIs, identity, or data sources without validation
+- Before any readout or scope handoff from discovery to build
+
+It complements but does not replace:
+- `risk-assumption-register` — which structures known risks into a register
+- `sow-proposal-reviewer` — which evaluates document quality and completeness
+- `scope-creep-detector` — which compares scope against discovery notes
+- `agent-governance` — which designs production controls for agents
+
+This skill's unique job is to find what the document **did not say clearly enough** before the team builds, prices, signs, or deploys.
+
+## Use This Skill When
+
+- Reviewing ADRs, proposals, RFPs, SOWs, POCs, MVP scopes, PRDs, BRDs
+- Reviewing architecture notes, solution diagrams, or integration plans
+- Reviewing meeting transcripts, workshop outputs, or backlog items
+- Reviewing RAG designs, agentic workflow designs, or AI solution outlines
+- Reviewing technical assumptions, data source inventories, or security questionnaires
+- The user asks "what are we missing" or "what could go wrong"
+- The user asks for a pre-build, pre-estimate, or pre-deployment risk review
+- The user wants a senior architect pre-mortem on a scope or design
+
+## Core Review Mindset
+
+Do not only summarize the document. **Interrogate it.**
+
+For each claim, ask:
+
+- What must be true for this to work?
+- What system, team, approval, data, API, permission, or environment is being assumed?
+- What could break during implementation?
+- What could block deployment?
+- What could create security or compliance exposure?
+- What could create unexpected scope growth?
+- What will the team wish they had asked earlier?
+
+Act as if a delivery architect, security architect, integration architect, data architect, product owner, enterprise architect, and support lead are all reviewing the same scope simultaneously.
+
+## Example Review Categories
+
+Review the document and structure them into categories. Read `references/gotcha-taxonomy.md` for the detailed gotcha patterns within each categories such as but not limited to:
+
+1. **Identity, Authentication, SSO, MFA** — Provider, protocol, claims, conditional access, service accounts
+2. **Authorization and Access Control** — Roles, entitlements, tenant isolation, separation of duties
+3. **API Gateway and Integration** — Gateway policies, API contracts, onboarding, mTLS
+4. **Legacy On-Prem Data and Application Access** — Network line of sight, VPN, firewall, batch windows
+5. **RAG Document Identity and ACL Preservation** — OIDs, chunk lineage, permission inheritance, citation integrity
+6. **Data Readiness** — Quality, ownership, availability, ground truth, PII classification
+7. **AI, Agent, and Model Risk** — Evaluation, hallucination handling, prompt injection, human approval
+8. **Security, Compliance, and Legal** — Data classification, residency, retention, audit, model provider terms
+9. **Operational Readiness** — Support model, runbook, monitoring, rollback, cost controls
+10. **Delivery, Scope, and Commercial Risk** — Bounded scope, acceptance criteria, estimation readiness
+
+For any category selected, the review should surface findings even when the document is silent — silence is often the signal.
+
+## Required Output
+
+Produce a structured report following the template in `templates/gotcha-review-report.md`:
+
+1. Executive summary
+2. Overall readiness rating (Green / Yellow / Orange / Red / Blocked)
+3. Gotcha heatmap (category × risk level)
+4. Critical findings (detailed finding format)
+5. Unknown unknowns register
+6. Assumption register
+7. Missing decision log
+8. Clarifying questions grouped by owner
+9. Mitigation backlog
+10. Go / no-go / proceed-with-conditions recommendation
+11. Source citation matrix
+
+## Finding Format
+
+Each finding must include:
+
+- **Title** — Clear statement of the gotcha
+- **Severity** — Critical / High / Medium / Low / Watch
+- **Category** — Which of the 10 review categories
+- **Confidence** — High / Medium / Low
+- **Timing** — Before estimate / Before build / Before integration / Before UAT / Before production / Post-MVP
+- **Source Evidence** — What the document said (or failed to say)
+- **Hidden Assumption** — What must be true but was not validated
+- **Why This Matters** — Impact on delivery, security, cost, or timeline
+- **Questions to Resolve** — Specific questions that need answers
+- **Recommended Mitigation** — Concrete action or design pattern
+- **Likely Owner** — Who should answer or act
+- **Citation** — Section, line, or page in the original document
+
+## Readiness Rating
+
+| Rating | Meaning |
+|--------|---------|
+| Green | Ready to proceed with normal delivery controls |
+| Yellow | Proceed, but resolve moderate risks before build completion |
+| Orange | Proceed only with explicit assumptions and mitigation plan |
+| Red | Not ready for build or fixed-fee commitment |
+| Blocked | Critical missing dependency prevents responsible estimation or delivery |
+
+## Severity Scale
+
+| Severity | Meaning |
+|----------|---------|
+| Critical | Could block delivery, cause data exposure, invalidate scope, or prevent deployment |
+| High | Likely to cause rework, delay, security concern, or major scope change |
+| Medium | Needs clarification or mitigation but may not block delivery |
+| Low | Improvement or hygiene item |
+| Watch | Not an issue yet, but should be monitored |
+
+## Citation Requirement
+
+When source documents are available, cite the original document for every material finding. Do not invent document evidence. If a finding is based on absence of information, state clearly:
+
+> "Not found in the provided document."
+
+When reviewing user-uploaded or connected files, cite source lines or document sections for every finding.
+
+## MCP-Aware Review
+
+When a finding depends on current implementation behavior of a vendor tool, SDK, framework, or platform, use available MCP tools where configured.
+
+Use Context7 when current documentation is needed for:
+- OIDC/SAML library behavior
+- API gateway policy details
+- pgvector, AI Search, or vector store implementation patterns
+- LangChain, LlamaIndex, or Semantic Kernel retrieval behavior
+- Microsoft.Extensions.AI or OpenAI SDK behavior
+- FastAPI, React, Vue, .NET, or Python SDK patterns
+- Azure, AWS, Google SDK guidance
+
+Do not rely on stale assumptions when current documentation can be retrieved through an MCP.
+
+## Workflow
+
+1. **Intake** — Read the provided document(s) completely. Note document type, delivery stage, and scope boundaries.
+2. **Claim extraction** — Identify every statement that implies a system, integration, permission, data source, process, or dependency.
+3. **Category sweep** — Walk through all 10 review categories. For each, identify what the document says, what it implies, and what it omits.
+4. **Finding generation** — For each identified gotcha, produce a full finding using the required format.
+5. **Cross-cutting analysis** — Look for patterns across findings (e.g., multiple findings pointing to the same unvalidated dependency).
+6. **Rating** — Assign overall readiness rating based on the aggregate severity and count of critical/high findings.
+7. **Report assembly** — Produce the full report following the template structure.
+8. **Citation validation** — Ensure every finding cites the source or explicitly states absence.
+
+## Reference Files
+
+- [references/gotcha-taxonomy.md](references/gotcha-taxonomy.md) — Complete taxonomy of gotcha patterns by category
+- [references/review-methodology.md](references/review-methodology.md) — Detailed review approach and interrogation patterns
+- [references/identity-auth-mfa.md](references/identity-auth-mfa.md) — Deep dive on identity, SSO, MFA gotchas
+- [references/authorization-access-control.md](references/authorization-access-control.md) — Authorization and access control patterns
+- [references/api-gateway.md](references/api-gateway.md) — API gateway integration gotchas
+- [references/legacy-onprem-access.md](references/legacy-onprem-access.md) — On-prem data and application access issues
+- [references/rag-document-identity-acl.md](references/rag-document-identity-acl.md) — RAG document identity, OID, ACL preservation
+- [references/ai-agent-risk.md](references/ai-agent-risk.md) — AI, agent, prompt, and model risk patterns
+- [references/data-readiness.md](references/data-readiness.md) — Data readiness, quality, and availability issues
+- [references/security-compliance.md](references/security-compliance.md) — Security, compliance, privacy, and legal concerns
+- [references/operational-readiness.md](references/operational-readiness.md) — Operational readiness and support model gaps
+- [references/delivery-commercial-risk.md](references/delivery-commercial-risk.md) — Delivery, scope, estimation, and commercial risks
+- [references/mcp-extension-guide.md](references/mcp-extension-guide.md) — MCP-aware documentation lookup guidance
+
+Read specific reference files when a category requires deeper interrogation or when findings in that category are numerous.
+
+## Templates
+
+- [templates/gotcha-review-report.md](templates/gotcha-review-report.md) — Full report template
+- [templates/unknown-unknowns-register.md](templates/unknown-unknowns-register.md) — Unknown unknowns register format
+- [templates/assumption-register.md](templates/assumption-register.md) — Assumption register format
+- [templates/clarifying-questions.md](templates/clarifying-questions.md) — Owner-grouped questions format
+- [templates/mitigation-backlog.md](templates/mitigation-backlog.md) — Prioritized mitigation backlog format
+- [templates/readiness-rating.md](templates/readiness-rating.md) — Readiness rating rubric
+- [templates/source-citation-matrix.md](templates/source-citation-matrix.md) — Citation traceability format
+
+## Quality Bar
+
+- Every critical and high finding must have a citation or explicit "not found" statement.
+- The report must cover all 10 categories even if some have no findings (state "No material findings" for clean categories).
+- Questions must be grouped by likely owner so they are actionable.
+- Mitigations must include timing (before estimate, before build, etc.).
+- The readiness rating must be justified by the findings, not assumed.
+- Do not pad the report with generic risks. Every finding must be tied to the specific document under review.
+- Do not present internal uncertainty as resolved fact. Label confidence levels honestly.
+
+## Common Pitfalls
+
+### Pitfall 1: Surface-Level Risk Lists
+Bad: "Data quality may be an issue."
+Better: Identify which specific data source, what quality dimension is at risk, who owns it, and what validation step would resolve it.
+
+### Pitfall 2: Missing the Silent Assumptions
+Bad: Only reviewing what the document says.
+Better: Explicitly interrogate what the document does NOT say — especially around identity, permissions, network access, and operational ownership.
+
+### Pitfall 3: Generic Boilerplate
+Bad: Copying standard risk language that applies to any project.
+Better: Every finding must be traceable to a specific claim, gap, or silence in the reviewed document.
+
+### Pitfall 4: Overwhelming Without Prioritization
+Bad: 50 findings with no severity differentiation.
+Better: Lead with the 3-5 critical items that could block delivery, then layer in high/medium/low.