architecture-readiness

What this skill does

# Architecture Readiness Skill

## Description

This skill helps Product Owners document business requirements and context before architecture design begins. It provides templates and guidance for creating Product Owner Specifications that feed into technical ARCHITECTURE.md documents.

The skill includes four primary functions:
1. **Requirements Elicitation**: Guided discovery interview to surface business requirements when no PO Spec exists
2. **PO Spec Creation**: Templates and guidance for documenting business requirements
3. **PO Spec Evaluation**: Scoring methodology to assess if a PO Spec is ready for architecture team handoff
4. **Async Intake**: File-based requirements extraction from tickets, emails, or documents — produces a gap report for async follow-up

## When to Use This Skill

Invoke this skill when:
- No existing PO Spec is found in the project and the user needs to capture business requirements
- User says they don't know where to start with business requirements
- User asks for requirements discovery, elicitation, or a requirements interview
- User asks to create a Product Owner Specification
- User asks about documenting business requirements for architecture
- User mentions "business context", "product requirements", or "requirements gathering" in relation to architecture
- User wants to prepare business documentation before technical architecture design
- User asks to evaluate or score a Product Owner Specification
- User wants to know if their PO Spec is ready for the architecture team
- User has business context in a file (ticket export, email, requirements doc) and wants to extract a PO Spec
- User says "async intake", "ticket context", "email context", or "intake from file"
- User provides a file path containing business requirements from an external async source

## Files in This Skill

- **REQUIREMENTS_ELICITATION_GUIDE.md**: Structured discovery interview methodology — 4 phases, probing techniques, Discovery Summary, and transition to PO Spec drafting
- **PRODUCT_OWNER_SPEC_GUIDE.md**: Comprehensive guide with 8-section template, examples, and best practices
- **templates/PO_SPEC_TEMPLATE.md**: Quick-start template for creating a new PO Specification
- **PO_SPEC_SCORING_GUIDE.md**: Weighted scoring methodology to evaluate PO Spec readiness (0-10 scale)
- **ASYNC_INTAKE_GUIDE.md**: File-based async intake methodology — extraction rules, keyword indicators, gap report template, and follow-up question generation

## How to Use This Skill

### 1. Async Intake (Non-Interactive)

⛔ **This flow NEVER transitions to elicitation.** It analyzes a file, produces a gap report with email-ready questions, and STOPS. The output is meant to be sent back to the requester asynchronously (email, ticket, Slack).

When business context arrives via ticket, email, or document (not a live conversation):

1. **Locate the context file**: Ask the user for the file path, or detect common patterns (`business-context.*`, `ticket-*.*`, `requirements-*.*`, `email-*.*`)
2. **Read and parse the file**: Load the full content
3. **Load scoring guide**: Read `PO_SPEC_SCORING_GUIDE.md` for the 8-section weighted rubric
4. **Load async intake guide**: Read `ASYNC_INTAKE_GUIDE.md` for extraction methodology and keyword indicators
5. **Map content to 8 PO Spec sections**: Extract what's present, mark what's missing per section
6. **Score against the rubric**: Calculate per-section completeness % and weighted total score
7. **Generate gap report** (`PO_SPEC_GAP_REPORT.md`): Structured markdown containing:
   - **Source file**: filename and processing date
   - **Extraction summary**: what was found mapped to each of the 8 sections with completeness %
   - **Score**: weighted total and per-section breakdown
   - **Gap report**: for each section below 75% completeness:
     - What's missing (specific sub-criteria from the scoring guide)
     - 2-3 ready-to-send questions for the requester
     - Priority level (HIGH / MEDIUM / LOW based on section weight)
   - **Ready-to-Send Message**: A complete, copyable email/ticket message block with subject line, prioritized gap questions, and sign-off — ready to paste into email, ticket, or Slack (see ASYNC_INTAKE_GUIDE.md for template)
   - **Next steps**: "Send the Ready-to-Send Message to the requester → receive answers → re-run async intake with the updated file"
8. **Save gap report**: Write to `PO_SPEC_GAP_REPORT.md` in the project root
9. **If score ≥ 7.5**: Also draft `PRODUCT_OWNER_SPEC.md` from the extracted data using `templates/PO_SPEC_TEMPLATE.md`; flag any inferred values with `[Default — confirm before architecture handoff]`
10. **If score < 7.5**: Save gap report only — do NOT draft a PO Spec, do NOT start elicitation. The gap report with its Ready-to-Send Message is the final output.

### 2. Requirements Elicitation (Interactive)

When this skill is activated and no existing PO Spec is found (or the user requests discovery/elicitation):

1. **Detect existing PO Spec**: Search for `PRODUCT_OWNER_SPEC.md`, `PO_SPEC.md`, `**/po-spec*`, `**/product-owner*`
   - If found: offer Evaluation or Creation workflows instead
   - If not found: proceed with elicitation
2. **Load the guide**: Read `REQUIREMENTS_ELICITATION_GUIDE.md` fully before starting
3. **Detect language**: Infer from user's first message; ask if ambiguous
4. **Conduct the 4-phase interview**:
   - Phase 1 — Foundation (Business Context, Stakeholders)
   - Phase 2 — Value & Boundaries (Objectives, Constraints) ← highest weight, invest depth here
   - Phase 3 — Behavior (Use Cases, User Stories) ← deepest phase, use case count reflects architecture complexity
   - Phase 4 — Experience & Measurement (UX Requirements, Success Metrics)
5. **Produce Discovery Summary**: Structured by all 8 sections with confidence levels and open questions; present for PO confirmation before drafting
6. **Draft PO Spec**: Load `templates/PO_SPEC_TEMPLATE.md`, fill from elicited data, self-score against `PO_SPEC_SCORING_GUIDE.md`
7. **Gap loop if needed**: If score < 7.5, ask targeted follow-ups on weakest sections; re-score; save final as `PRODUCT_OWNER_SPEC.md`

### 3. PO Spec Creation (Template-Guided)

When this skill is activated for document creation:

1. **Read the guide**: Load PRODUCT_OWNER_SPEC_GUIDE.md to understand the 8-section structure
2. **Understand user context**: Ask clarifying questions about their product/feature
3. **Provide appropriate template**:
   - For guidance and understanding: Reference PRODUCT_OWNER_SPEC_GUIDE.md
   - For quick start: Provide templates/PO_SPEC_TEMPLATE.md
4. **Guide document creation**: Help user fill out each section with business context
5. **Reference mapping**: Explain how PO Spec maps to ARCHITECTURE.md (see guide Section "Mapping to ARCHITECTURE.md")

### 4. PO Spec Evaluation (Score Existing)

When this skill is activated to evaluate a PO Spec:

1. **Read the scoring guide**: Load PO_SPEC_SCORING_GUIDE.md to understand the weighted scoring methodology
2. **Read the PO Spec**: Load the user's Product Owner Specification document
3. **Evaluate each section**: Assess completeness of all 8 sections using the evaluation criteria
4. **Calculate weighted score**: Apply section weights and compute total score (0-10 scale)
5. **Provide detailed feedback**:
   - Overall score and readiness interpretation
   - Section-by-section breakdown showing completeness %
   - Identify gaps in critical sections (Use Cases, Business Constraints, Business Objectives)
   - Provide actionable recommendations for improvement
6. **Determine readiness**: Score ≥7.5/10 indicates ready for architecture team handoff

## Key Principles

- **Business-focused**: No technical details or architecture decisions in PO Spec
- **User-centric**: Emphasize user needs, personas, and pain points
- **Measurable**: All goals and success criteria must be quantifiable
- **Constraint-aware**: Document all business constraints (budget, timeline, compliance)

## Inte