draft-technical-approach

name	draft-technical-approach
description	Create an architecture.yaml artifact with technology selections, NFRs, platforms, integrations, and agentic PCAM design from a features specification
user-invocable	false
model	sonnet
allowed-tools	Read, Write

draft-technical-approach

Model-invocable skill for creating architecture specifications as structured YAML.

Purpose

Transform a features specification (behaviors, invariants, feature scope) into a concrete architecture.yaml artifact that names specific technologies for every architectural component and makes all technology selection decisions. The artifact must be specific enough that an implementer can begin coding without making technology selection decisions.

You DO create the architecture.yaml artifact. You do NOT validate it or decide what happens next.

Output Schema

The output MUST conform to schemas/architecture.yaml in this skill's directory. Read the schema before producing output. Every field defined in the schema must be present in the output YAML. The schema is the contract — if it's in the schema, it's in the output.

Input

Receive from agent:

• features_yaml_path — (required) Path to features.yaml
• intent — (optional) Product intent string for additional context
• vision_path — (optional) Path to a locked vision document for enrichment
• output_base — (required) Base path for output, e.g., .garura/product/architecture/
• profiles_ref — (optional) Path to product.yaml containing profiles section. When provided, NFR profile levels drive the nfrs section, and profile values inform technology selection reasoning via LTM architecture knowledge "When to Choose" matching.
• product_yaml_path — (optional) Path to product.yaml for profile and context extraction
• roadmap_yaml_path — (optional) Path to roadmap.yaml for epic/feature context
• ltm_architecture_path — (optional) Path to LTM architecture knowledge directory (default: ~/.garura/core/memory/knowledge/arch/)

Process

1. Read features specification: Load the features_yaml_path document. Extract: product identity, architectural invariants, feature list, behaviors, blast_radius entries, and scope boundaries.

2. Read vision and profiles (if provided): If vision_path or product_yaml_path is provided, load and extract strategic goals, target users, value proposition, and profiles for architectural context. If profiles_ref is provided, extract all three profile axes (PP, NFR, QP) — these are primary inputs for technology selection and NFR derivation.

2b. Read LTM architecture knowledge (if provided): If ltm_architecture_path is provided, read the _index.md and relevant architecture files. Match "When to Choose" and "When to Avoid" prose against profile values. This informs pattern, stack, platform, and data store selection. Load files whose search patterns match the product's domain and profile characteristics.

3. Check for existing artifact: Read {output_base}/architecture.yaml. If LOCKED, return structured failure: "architecture.yaml is LOCKED -- drop to DRAFT first." If DRAFT exists, overwrite (agent re-triggered DRAFT).

4. Compose architecture.yaml: Build the artifact conforming to the architecture.yaml schema. Every architectural component MUST map to a named technology -- specific databases, frameworks, SDKs, hosting platforms, libraries. No vague references like "a relational database" or "a message queue." Every technology choice MUST include rationale.

   Top-level fields:

   • slug — from features.yaml slug
   • status — always DRAFT
   • created_at, updated_at — current ISO-8601 timestamp
   • features_ref — path to features.yaml

   principles section: Implementation principles guiding all technology and design decisions. Derived from the features.yaml architectural invariants. Each principle gets a stable ID (TP1, TP2, ...) with principle statement and rationale.

   architecture section:

   • topology — ASCII diagram or structured description of the system topology showing deployment units and communication patterns
   • deployment_units — list of named units with responsibility and communication protocol/pattern

   nfrs section (NON-FUNCTIONAL REQUIREMENTS): Explicit, prioritized NFR statements for:

   • performance — response time targets, throughput thresholds
   • scalability — concurrency, volume expectations
   • security — encryption, auth, data protection requirements
   • availability — uptime SLA, recovery objectives
   • compliance — regulatory or data residency requirements Each requirement gets a requirement string and priority (must | should | nice-to-have).

   When profiles_ref is provided: NFR requirements MUST be derived from the NFR Profile levels in product.yaml. Map each NFR dimension level to concrete, measurable requirements:

   • NFR-1 (Risk) level 3 → "Monitoring and alerting for all customer-facing endpoints"

Output

architecture_yaml:
  path: "{full path to architecture.yaml}"
  architecture_yaml_path: "{full path to architecture.yaml}"
  sections:
    - principles
    - architecture
    - nfrs
    - stack
    - platforms
    - integrations
    - technical_risks
    - deployment
    - observability
    - agentic
  has_agentic: true | false
  status: "DRAFT"

IMPORTANT: This skill produces an artifact and returns metadata. The calling agent receives this output and decides what to do next. Do NOT instruct the agent to return or stop.

Constraints

• NEVER use vague technology references -- every component must name a specific product, library, framework, or platform
• NEVER overwrite a LOCKED architecture.yaml -- return structured failure
• NEVER invent product behaviors -- derive architecture from features.yaml behaviors and invariants
• NEVER confuse implementation machinery for the product architecture -- the architecture serves the product spec, not the other way around
• ALWAYS set status: DRAFT in the written artifact
• ALWAYS include rationale for every technology selection
• ALWAYS include the nfrs section with at least performance and security entries
• ALWAYS include platforms and integrations sections (may be empty lists for greenfield with no external dependencies)
• ALWAYS ensure the artifact is concrete enough for a code-builder agent to implement from without making technology selection decisions
• ALWAYS include features_served references in platforms and integrations entries so the reader knows which features depend on each external system
• WHEN profiles_ref is provided, ALWAYS derive NFR requirements from NFR Profile levels with traceable rationale
• WHEN ltm_architecture_path is provided, ALWAYS read and reference LTM architecture knowledge in technology selection reasoning
• ALWAYS include profiles_ref in the output artifact when profiles were used as input
• Audience is architects and implementers -- write with precision, not marketing language

Version

Field	Value
Version	2.0.0
Category	analysis