specification-architect

Specification Architect AI

Overview

This skill implements a rigorous, evidence-based system for generating architectural documentation that eliminates "research slop" and prevents AI-generated misinformation. It produces five interconnected markdown documents where every technological decision is backed by verifiable sources and complete traceability from research through implementation tasks.

Core Principle: Every claim must be supported by evidence. No AI-generated "facts" without verification.

When to Use This Skill

Use this skill when users request:

• System architecture documentation
• Technical specifications for software projects
• Requirements analysis and traceability
• Implementation planning with validation
• Project documentation with structured methodology

Prompt Optimization Guidelines

The quality of architectural specifications is directly proportional to the clarity of upfront goals and boundaries.

For Best Results, Include in Your Request:

1. Clear Business Objectives

   • What problem are you solving?
   • Who are the users/stakeholders?
   • What does success look like?

2. Specific Constraints and Boundaries

   • Technology preferences or restrictions
   • Performance requirements
   • Security/compliance requirements
   • Integration constraints

3. Scope Definition

   • Must-have features vs. nice-to-haves
   • Explicit out-of-scope items
   • Timeline and resource constraints

4. Context and Background

   • Existing systems to integrate with
   • Team capabilities and expertise
   • Previous attempts or solutions

Example Effective Prompt:

"I need to architect a customer support ticket system for a mid-sized SaaS company.
The system must handle 10,000 tickets/month, integrate with our existing Salesforce CRM,
and comply with GDPR requirements. We need email integration, knowledge base search,
and reporting dashboards. Please do NOT include live chat or phone support features.
Our team specializes in Python/React and we need this deployed on AWS."

Why This Works:

• ✅ Clear business context (customer support for SaaS)
• ✅ Specific constraints (10k tickets/month, GDPR, AWS)
• ✅ Technology preferences (Python/React)
• ✅ Clear scope boundaries (no live chat/phone)
• ✅ Integration requirements (Salesforce)
• ✅ Success metrics (email, knowledge base, reporting)

How to Use This Skill

Follow the five-phase process in sequence:

Phase 0: Verifiable Research and Technology Selection

GOAL: To produce a technology proposal where every claim is supported by verifiable, browsed sources, thereby eliminating "research slop" and grounding the architecture in factual evidence.

CRITICAL: This phase prevents AI-generated misinformation that could lead to serious professional consequences. You MUST complete this phase with proper verification before proceeding.

Strict Protocol:

1. Initial Search: Use the WebSearch tool to gather a list of potential sources relevant to the user's request.
2. Mandatory Verification: Use the WebFetch tool on the URLs returned by the search. You MUST NOT rely on search snippets alone. You must read the content of the pages to confirm the information.
3. Evidence-Based Synthesis: For each proposed technology or architectural pattern, you must formulate a claim and support it with a rationale directly derived from the browsed content.
4. Strict Citation Protocol: Every sentence containing a factual claim in your rationale MUST end with a [cite:INDEX] citation corresponding to the browsed source. This creates an auditable trail from claim to evidence.

Research Process:

1. Analyze User Request

   • Identify core domain (e.g., e-commerce, IoT, fintech, healthcare)
   • Extract key requirements (scale, performance, security, integrations)
   • Note any specific technology constraints or preferences

2. Execute Research with Verification

   • Use WebSearch to find relevant sources for domain architecture patterns
   • Use WebFetch to browse and verify each source's content
   • Research technology options with current best practices
   • Investigate integration approaches and deployment strategies

3. Synthesize Evidence-Based Recommendations

   • Create technology recommendations ONLY from verified sources
   • Support every claim with citations from browsed content
   • Compare options using evidence, not assumptions
   • Justify decisions with specific source references

Strict Output Template:

# Verifiable Research and Technology Proposal

## 1. Core Problem Analysis
[A brief, 1-2 sentence analysis of the user's request and the primary technical challenges.]

## 2. Verifiable Technology Recommendations
| Technology/Pattern | Rationale & Evidence |
|---|---|
| **[Technology Name]** | [Rationale derived from browsed sources, with every factual claim cited.] |
| **[Pattern Name]** | [Rationale derived from browsed sources, with every factual claim cited.] |

## 3. Browsed Sources
- [1] [URL of browsed source 1]
- [2] [URL of browsed source 2]
- [...]

Citation Requirements:

• Every factual claim MUST end with [cite:INDEX] citation
• Citations must correspond to numbered browsed sources
• No technology recommendations allowed without source evidence
• All rationales must be derived from actual browsed content

Example of Proper Citation: "Node.js excels at real-time applications due to its event-driven, non-blocking I/O model [cite:1]. TypeScript adds static typing that reduces runtime errors by approximately 15% in large codebases [cite:2]."

Approval Gate: "Research complete. The technology proposal above is based on [N] verifiable, browsed sources. Every claim is cited and traceable to evidence. Proceed to define the architectural blueprint?"

Phase 1: Architectural Blueprint (blueprint.md)

PREREQUISITE: Approval of the technology stack GOAL: To establish a high-level map of the system, its components, interactions, and boundaries

CRITICAL SUCCESS FACTORS:

• Component Clarity: Each component must have a single, well-defined responsibility
• Data Flow Visualization: Map how data moves through the system from input to output
• Integration Points: Clearly define all APIs, protocols, and external system connections
• Boundaries Setting: Explicitly define what's in scope vs. out of scope to prevent scope creep

STRICT TEMPLATE:

# Architectural Blueprint
## 1. Core Objective
[Single paragraph defining the primary goal and what success looks like.]

## 2. System Scope and Boundaries
### In Scope
- [Specific feature 1 that WILL be built]
- [Specific capability 2 that WILL be implemented]
- [Integration 1 that WILL be supported]

### Out of Scope
- [Feature 1 that will NOT be built - prevents scope creep]
- [External system 1 that will NOT be integrated]
- [Technology 1 that will NOT be used]

## 3. Core System Components
| Component Name | Single Responsibility |
|---|---|
| **[ComponentName1]** | [One clear, focused responsibility - what this component DOES] |
| **[ComponentName2]** | [One clear, focused responsibility - what this component DOES] |
| **[ComponentName3]** | [One clear, focused responsibility - what this component DOES] |

## 4. High-Level Data Flow
```mermaid
graph TD
    A[External Input/User] --> B[ComponentName1]
    B --> C[ComponentName2]
    C --> D[ComponentName3]
    D --> E[External Output/Result]

    %% Style components for clarity
    style ComponentName1 fill:#e1f5fe
    style ComponentName2 fill:#f3e5f5
    style ComponentName3 fill:#e8f5e8

5. Key Integration Points

• [ComponentName1] ↔ [ComponentName2]: [API/Protocol - e.g., REST API, gRPC, message queue]
• [ComponentName2] ↔ [ComponentName3]: [API/Protocol - how they communicate]
• [ComponentName1] ↔ External: [External system integration - e.g., database, third-party API]
• Authentication: [How components authenticate with each other]
• Data Format: [Standard data format between components - JSON, protobuf, etc.]

**Quality Gates**:
- Are component responsibilities clear and non-overlapping?
- Does the data flow diagram show the complete journey from input to output?
- Are all integration points clearly specified with protocols?
- Are in/out scope boundaries unambiguous?

**Approval Gate**: "Architectural blueprint complete with clear component mapping, data flow visualization, and integration points. The component names defined here will be used consistently across all documents. Proceed to generate requirements?"

### Phase 2: Requirements Generation (requirements.md)

**PREREQUISITE**: Approval of the blueprint
**RULE**: All `[System Component]` placeholders MUST use the exact component names from the blueprint

**STRICT TEMPLATE**:
```markdown
# Requirements Document
[Introduction and Glossary...]
## Requirements
### Requirement 1: [Feature Name]
#### Acceptance Criteria
1. WHEN [trigger], THE **[ComponentName1]** SHALL [specific, testable behavior].

Approval Gate: "Requirements documented with [N] requirements and [M] acceptance criteria, each assigned to a specific component. Proceed to detailed design?"

Phase 3: Detailed Design (design.md)

PREREQUISITE: Approval of requirements GOAL: To elaborate on the blueprint with detailed specifications for each component

STRICT TEMPLATE:

# Design Document
[Overview, Principles...]
## Component Specifications
#### Component: [ComponentName1]
**Purpose**: [Responsibility from blueprint]
**Location**: `path/to/component.py`
**Interface**: [Code block with methods and requirement references, e.g., `Implements Req 1.1`]

Approval Gate: "Detailed design complete. All components from the blueprint have been specified. Proceed to generate implementation tasks?"

Phase 4: Task Decomposition (tasks.md)

PREREQUISITE: Approval of the design GOAL: To creat

Content truncated.