name: review-architecture description: Review, create, or update docs/architecture.md to match organizational standards with accurate technical content allowed-tools: Bash(gh:), Bash(git:), Bash(ls:), Bash(cat:), Bash(head:), Bash(tail:), Bash(jq:), Bash(find:), Bash(wc:*), Read, Write, Edit, Glob, Grep

Review Architecture Documentation

Review the docs/architecture.md file in a repository and create or update it to match organizational standards. This skill deeply analyzes the codebase to ensure architecture documentation is accurate, complete, and reflects the actual implementation. Works for all repository types and languages.

Architecture Document Types

There are two types of architecture documents based on project type:

Standard Projects

Required H2 sections:

## Table of Contents
## Architecture diagram
## Software units
## Software of Unknown Provenance
## Critical algorithms
## Risk controls

ML/DL Projects

For machine learning and deep learning projects, required H2 sections:

## Table of Contents
## Datasets
## Data Preprocessing
## Data Splits
## Model Architecture
## Model Training
## Model Evaluation
## Software of Unknown Provenance
## Risk controls
## Model Deployment

Step 1: Gather Repository Information

Run these commands to collect repository metadata:

# Get organization and repository name
gh repo view --json owner,name,visibility,description

# Check if docs/architecture.md exists
ls -la docs/architecture.md 2>/dev/null || echo "No docs/architecture.md found"

# Check if docs directory exists
ls -la docs/ 2>/dev/null || echo "No docs directory found"

# Get last modified date of architecture.md vs source code
stat -f "%Sm" docs/architecture.md 2>/dev/null || stat -c "%y" docs/architecture.md 2>/dev/null || echo "N/A"
find src lib app pkg internal cmd . -maxdepth 2 -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.go" -o -name "*.rs" 2>/dev/null |
  head -20 | xargs -I {} stat -f "%Sm {}" {} 2>/dev/null | sort -r | head -5

Store these values:

• organization: The owner/organization name
• repository: The repository name
• has_architecture_doc: true/false
• has_docs_dir: true/false
• doc_last_modified: Date of last architecture.md change
• code_last_modified: Date of most recent source code change

Step 2: Check if Architecture Documentation is Required

Some repository types do not require architecture documentation. Detect these and create an exemption file instead of nonsensical documentation.

Check for Existing Exemption

# Check if already marked as not required
head -5 docs/architecture.md 2>/dev/null | grep -q "Architecture documentation is not required" && echo "EXEMPT" ||
  echo "NOT_EXEMPT"

If the file already contains the exemption marker, stop here - no further action needed.

Detect Exempt Repository Types

Homebrew Taps:

# Check for Homebrew tap pattern
gh repo view --json name --jq '.name' | grep -qE "^homebrew-" && echo "HOMEBREW_TAP"
ls -la Formula/ Casks/ 2>/dev/null

Claude Code Plugins:

# Check for Claude Code plugin
ls -la .claude-plugin/plugin.json skills/ commands/ 2>/dev/null

Configuration/Dotfiles Repositories:

# Check if repo is mostly config files
find . -maxdepth 2 -type f \( -name "*.yml" -o -name "*.yaml" -o -name "*.json" -o -name "*.toml" -o -name ".*" \) 2>/dev/null |
  wc -l
find . -maxdepth 2 -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.go" -o -name "*.rs" -o -name "*.rb" -o -name "*.java" \) 2>/dev/null |
  wc -l

Documentation-Only Repositories:

# Check if repo is only documentation
find . -maxdepth 3 -type f -name "*.md" 2>/dev/null | wc -l
find . -maxdepth 3 -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.go" -o -name "*.rs" -o -name "*.rb" \) 2>/dev/null |
  wc -l

GitHub Profile Repositories:

# Check if repo name matches owner (profile README repo)
OWNER=$(gh repo view --json owner --jq '.owner.login')
NAME=$(gh repo view --json name --jq '.name')
[ "$OWNER" = "$NAME" ] && echo "PROFILE_REPO"

GitHub Actions:

# Check for GitHub Action
ls -la action.yml action.yaml 2>/dev/null
cat action.yml action.yaml 2>/dev/null | grep -q "runs:" && echo "GITHUB_ACTION"

Terraform Modules:

# Check for Terraform module (no main application)
ls -la *.tf modules/ 2>/dev/null
find . -name "*.tf" -not -path "*/.terraform/*" 2>/dev/null | head -5

Ansible Roles/Playbooks:

# Check for Ansible
ls -la playbooks/ roles/ tasks/ handlers/ ansible.cfg 2>/dev/null

Kubernetes/Helm Charts:

# Check for Helm chart or K8s manifests only
ls -la Chart.yaml values.yaml templates/ 2>/dev/null
find . -name "*.yaml" -path "*/templates/*" 2>/dev/null | head -5

Meta/Organization Repositories:

# Check for org-wide config repos
gh repo view --json name --jq '.name' | grep -qiE "^\.github$|^meta$|^org-|^team-|^-config$|-settings$" && echo "META_REPO"

Exempt Repository Types

Create Exemption File

If the repository matches an exempt type, create the exemption file:

mkdir -p docs

Exemption Template:

# Architecture Design

Architecture documentation is not required for this repository.

## Reason

This repository is a **{type}** which does not contain application software requiring architecture documentation.

### Repository Type: {type}

{Description of why this type doesn't need architecture docs}

## Documentation

For more information about this repository type, see:

{Link to relevant documentation}

## When This Might Change

Architecture documentation would be required if this repository evolves to include:

- Application source code with business logic
- Software components that interact with each other
- External dependencies that need to be documented (SOUP)
- Critical algorithms or risk controls

If the repository scope changes, remove this file and run the architecture review again.

Exemption Messages and Documentation Links by Type:

After creating the exemption file, STOP - do not proceed with architecture documentation steps.

Step 3: Detect Project Type (Standard vs ML/DL)

Determine if this is a Machine Learning / Deep Learning project.

Detection Method 1: Repository Name Patterns

gh repo view --json name --jq '.name'

ML/DL indicators in repository name:

• Contains -ml, -dl, -ai
• Ends with -model, -models
• Contains machine-learning, deep-learning

Detection Method 2: ML/DL Framework Dependencies

Python projects:

# Check requirements.txt
cat requirements.txt 2>/dev/null | grep -iE "tensorflow|pytorch|torch|keras|scikit-learn|sklearn|xgboost|lightgbm|transformers|huggingface|jax|mlflow|wandb|optuna|numpy|pandas|scipy"

# Check pyproject.toml
cat pyproject.toml 2>/dev/null | grep -iE "tensorflow|pytorch|torch|keras|scikit-learn|sklearn|xgboost|lightgbm|transformers|huggingface|jax|mlflow|wandb|optuna"

# Check poetry.lock or requirements for exact versions
cat poetry.lock requirements.txt 2>/dev/null | grep -iE "^(tensorflow|torch|keras|scikit-learn)==[0-9]" | head -10

Node.js projects:

cat package.json 2>/dev/null | jq -r '.dependencies, .devDependencies | keys[]' 2>/dev/null | grep -iE "tensorflow|brain|ml5|synaptic"

Detection Method 3: ML/DL Directory Structure

# Check for ML-specific directories
ls -la models/ model/ training/ train/ data/ datasets/ notebooks/ checkpoints/ weights/ experiments/ 2>/dev/null

# Check for Jupyter notebooks
find . -maxdepth 3 -name "*.ipynb" 2>/dev/null | wc -l

# Check for model files
find . -maxdepth 3 \( -name "*.h5" -o -name "*.pkl" -o -name "*.pt" -o -name "*.pth" -o -name "*.onnx" -o -name "*.pb" -o -name "*.safetensors" \) 2>/dev/null |
  head -5

Detection Method 4: Code Pattern Analysis

# Search for ML patterns in Python files
grep -rl "model\.fit\|model\.train\|DataLoader\|tf\.keras\|torch\.nn\|sklearn\." --include="*.py" . 2>/dev/null | wc -l

Classification Rules

Classify as ML/DL project if ANY of these are true:

• Repository name matches ML/DL patterns
• ML frameworks found in dependencies (tensorflow >= any, pytorch/torch, keras, scikit-learn)
• Has models/, training/, datasets/ directories with content
• Contains 3+ Jupyter notebooks
• Has model checkpoint files (.h5, .pt, .pth, .onnx, .pkl)
• 5+ files contain ML code patterns

Otherwise, classify as Standard project.

Store:

• project_type: "ml_dl" or "standard"
• ml_frameworks: List of detected ML frameworks with versions
• has_model_files: true/false

Step 4: Deep Codebase Analysis - Standard Projects

4.1 Architecture Diagram Verification

# Find existing diagram files
find . -maxdepth 3 \( -name "*.png" -o -name "*.svg" -o -name "*.drawio" -o -name "*.mmd" -o -name "*.mermaid" -o -name "*.puml" \) 2>/dev/null |
  grep -iE "arch|diagram|overview|system|structure"

# Check if diagrams are referenced in architecture.md
grep -iE "\!\[.*\]\(.*\.(png|svg|drawio)\)" docs/architecture.md 2>/dev/null
grep -iE "```mermaid" docs/architecture.md 2>/dev/null

Verification:

• If diagram exists, check modification date vs code changes
• Flag if diagram is older than significant code changes
• List components shown in diagram vs actual modules

4.2 Software Units Deep Analysis

Discover actual module structure:

# Python packages
find . -name "__init__.py" -not -path "*/venv/*" -not -path "*/.venv/*" -not -path "*/node_modules/*" 2>/dev/null |
  sed 's|/[^/]*$||' | sort -u

# Node.js/TypeScript modules
cat package.json 2>/dev/null | jq -r '.main, .exports | if type == "object" then keys[] else . end' 2>/dev/null
ls -la src/ lib/ 2>/dev/null

# Go packages
find . -name "*.go" -not -path "*/vendor/*" 2>/dev/null | xargs -I {} dirname {} | sort -u

# Rust crates
find . -name "Cargo.toml" 2>/dev/null | xargs -I {} dirname {}

For each discovered module, extract:

# Python: Get module docstring and main classes/functions
head -30 {module}/__init__.py 2>/dev/null
grep -E "^class |^def |^async def " {module}/*.py 2>/dev/null | head -20

# Node.js: Get exports
grep -E "^export |^module\.exports" {module}/index.{js,ts} {module}.{js,ts} 2>/dev/null | head -20

# Go: Get package doc and exported functions
head -20 {module}/*.go 2>/dev/null | grep -E "^package |^// |^func [A-Z]"

Cross-reference with documentation:

• Read the "Software units" section from docs/architecture.md
• Compare listed modules vs discovered modules
• Flag modules in code but not in docs
• Flag modules in docs but not in code
• Check if descriptions match actual functionality

4.3 Software of Unknown Provenance (SOUP) Deep Analysis

Extract complete dependency list with versions:

# Python - from lock files (exact versions)
cat poetry.lock 2>/dev/null | grep -E "^name = |^version = " | paste - - | head -50
cat Pipfile.lock 2>/dev/null | jq -r '.default, .develop | to_entries[] | "\(.key)==\(.value.version)"' 2>/dev/null |
  head -50
pip freeze 2>/dev/null | head -50

# Node.js - from lock files
cat package-lock.json 2>/dev/null |
  jq -r '.packages | to_entries[] | select(.key != "") | "\(.key | split("/") | last)@\(.value.version)"' 2>/dev/null |
  head -50
cat yarn.lock 2>/dev/null | grep -E "^\"?[a-z@].*:$" -A 1 | grep -E "version" | head -50

# Go modules
cat go.sum 2>/dev/null | awk '{print $1, $2}' | sort -u | head -50

# Rust
cat Cargo.lock 2>/dev/null | grep -E "^name = |^version = " | paste - - | head -50

Extract license information:

# For Node.js
cat package-lock.json 2>/dev/null |
  jq -r '.packages | to_entries[] | select(.value.license) | "\(.key): \(.value.license)"' 2>/dev/null | head -30

# Check for license files in vendor/node_modules
find node_modules -maxdepth 2 -name "LICENSE*" 2>/dev/null | head -20 |
  xargs -I {} sh -c 'echo "=== {} ===" && head -5 {}'

Cross-reference with documentation:

• Read "Software of Unknown Provenance" section
• Compare documented dependencies vs actual dependencies
• Flag version mismatches
• Flag missing dependencies
• Flag dependencies in docs that no longer exist
• Check for missing licenses (critical for compliance)

4.4 Critical Algorithms Deep Analysis

Discover algorithm implementations:

# Search for algorithm-related files
find . -name "*algorithm*" -o -name "*crypto*" -o -name "*hash*" -o -name "*sort*" -o -name "*search*" -o -name "*calculate*" -o -name "*compute*" -o -name "*process*" -o -name "*engine*" 2>/dev/null |
  grep -v node_modules | grep -v venv

# Search for cryptographic operations
grep -rn "crypto\|encrypt\|decrypt\|hash\|hmac\|sha\|md5\|aes\|rsa" --include="*.py" --include="*.js" --include="*.ts" --include="*.go" --include="*.rs" . 2>/dev/null |
  grep -v node_modules | grep -v venv | head -20

# Search for complex mathematical operations
grep -rn "matrix\|vector\|gradient\|derivative\|integral\|fourier\|transform" --include="*.py" --include="*.js" --include="*.ts" --include="*.go" --include="*.rs" . 2>/dev/null |
  grep -v node_modules | grep -v venv | head -20

# Search for custom data structures
grep -rn "class.*Tree\|class.*Graph\|class.*Queue\|class.*Stack\|class.*Heap" --include="*.py" --include="*.js" --include="*.ts" --include="*.go" --include="*.rs" . 2>/dev/null |
  head -20

For each discovered algorithm, extract details:

• Read the file containing the algorithm
• Extract function/class signature
• Extract docstring/comments explaining the algorithm
• Note time/space complexity if documented

Cross-reference with documentation:

• Compare documented algorithms vs discovered implementations
• Flag undocumented critical algorithms
• Verify file paths in docs match actual locations
• Check if complexity claims are accurate

4.5 Risk Controls Deep Analysis

Discover security measures:

# Authentication/Authorization patterns
grep -rn "auth\|login\|session\|token\|jwt\|oauth\|permission\|role\|acl" --include="*.py" --include="*.js" --include="*.ts" --include="*.go" . 2>/dev/null |
  grep -v node_modules | grep -v test | head -20

# Input validation patterns
grep -rn "validate\|sanitize\|escape\|filter\|whitelist\|blacklist" --include="*.py" --include="*.js" --include="*.ts" --include="*.go" . 2>/dev/null |
  grep -v node_modules | head -20

# Error handling patterns
grep -rn "try:\|catch\|except\|error\|throw\|panic\|recover" --include="*.py" --include="*.js" --include="*.ts" --include="*.go" . 2>/dev/null |
  grep -v node_modules | grep -v test | wc -l

# Logging patterns
grep -rn "log\.\|logger\.\|logging\.\|console\.log\|fmt\.Print" --include="*.py" --include="*.js" --include="*.ts" --include="*.go" . 2>/dev/null |
  grep -v node_modules | grep -v test | head -20

Check for security configurations:

# Environment variables
grep -rn "process\.env\|os\.environ\|os\.Getenv\|env::" --include="*.py" --include="*.js" --include="*.ts" --include="*.go" --include="*.rs" . 2>/dev/null |
  grep -v node_modules | head -20

# Security headers/middleware
grep -rn "helmet\|cors\|csrf\|xss\|rate.limit\|security" --include="*.py" --include="*.js" --include="*.ts" --include="*.go" . 2>/dev/null |
  grep -v node_modules | head -10

Step 5: Deep Codebase Analysis - ML/DL Projects

5.1 Datasets Deep Analysis

Discover dataset definitions:

# Find dataset classes/loaders
grep -rn "class.*Dataset\|DataLoader\|tf\.data\|torch\.utils\.data" --include="*.py" . 2>/dev/null | grep -v venv |
  head -20

# Find data directories and files
find data datasets raw processed -type f 2>/dev/null | head -30
ls -la data/ datasets/ 2>/dev/null

# Extract dataset statistics
wc -l data/*.csv datasets/*.csv 2>/dev/null
find data datasets -name "*.json" -exec wc -l {} \; 2>/dev/null | head -10

For each dataset, extract:

• Read dataset class implementation
• Extract data loading logic
• Note data format, features, labels
• Extract any data validation rules

Cross-reference with documentation:

• Compare documented datasets vs actual data files
• Verify dataset sizes/statistics
• Check data source URLs are still valid
• Flag undocumented datasets

5.2 Data Preprocessing Deep Analysis

Discover preprocessing code:

# Find preprocessing functions/classes
grep -rn "def preprocess\|def transform\|def normalize\|def augment\|def clean\|class.*Transform\|class.*Preprocess" --include="*.py" . 2>/dev/null |
  grep -v venv | head -20

# Find preprocessing pipelines
grep -rn "Pipeline\|Compose\|Sequential.*transform" --include="*.py" . 2>/dev/null | grep -v venv | head -10

For each preprocessing step, extract:

• Read the preprocessing function/class
• Extract input/output specifications
• Note any parameters or configurations
• Check for data augmentation techniques

Cross-reference with documentation:

• Compare documented preprocessing steps vs actual code
• Verify transformation order matches implementation
• Check if parameters in docs match code defaults

5.3 Data Splits Deep Analysis

Discover split implementation:

# Find train/test split code
grep -rn "train_test_split\|split\|StratifiedKFold\|KFold\|random_split" --include="*.py" . 2>/dev/null | grep -v venv |
  head -15

# Extract split ratios from code
grep -rn "test_size\|val_size\|train_size\|split.*=" --include="*.py" . 2>/dev/null | grep -v venv | head -15

# Check for split configuration files
cat config.yaml config.yml config.json 2>/dev/null | grep -iE "split|train|val|test"

Cross-reference with documentation:

• Compare documented split ratios vs actual code
• Verify split methodology description
• Check if cross-validation strategy matches

5.4 Model Architecture Deep Analysis

Discover model definitions:

# Find model classes
grep -rn "class.*Model\|class.*Net\|class.*Network\|nn\.Module\|tf\.keras\.Model" --include="*.py" . 2>/dev/null |
  grep -v venv | head -20

# Find model configuration
cat model_config.json model_config.yaml config/model.* 2>/dev/null

For each model, extract architecture details:

# Read model class definition (first 100 lines)
# For each model file found above, read it to extract:
# - Layer definitions
# - Forward pass logic
# - Input/output shapes

# Extract layer specifications from code
grep -rn "nn\.Linear\|nn\.Conv\|Dense\|Conv2D\|LSTM\|Transformer\|Attention" --include="*.py" . 2>/dev/null |
  grep -v venv | head -30

# Check for model summary/print
grep -rn "model\.summary\|print.*model\|torchsummary" --include="*.py" . 2>/dev/null | grep -v venv | head -5

Cross-reference with documentation:

• Compare documented architecture vs actual model code
• Verify layer specifications match implementation
• Check input/output shapes are accurate
• Flag architecture changes not reflected in docs

5.5 Model Training Deep Analysis

Discover training configuration:

# Find training scripts
find . -name "train*.py" -o -name "*training*.py" -o -name "main.py" 2>/dev/null | grep -v venv

# Extract hyperparameters from code
grep -rn "learning_rate\|lr\|batch_size\|epochs\|optimizer\|Adam\|SGD\|loss" --include="*.py" . 2>/dev/null |
  grep -v venv | head -30

# Check for config files
cat config.yaml config.yml config.json training_config.* hyperparameters.* 2>/dev/null | head -50

# Find argument parsers for hyperparameters
grep -rn "add_argument.*lr\|add_argument.*batch\|add_argument.*epoch" --include="*.py" . 2>/dev/null | head -15

Extract actual training parameters:

• Default values in code
• Values in config files
• Command-line argument defaults

Cross-reference with documentation:

• Compare documented hyperparameters vs actual code
• Check if optimizer, loss function, lr match
• Verify batch size, epochs are accurate
• Flag any training procedure changes

5.6 Model Evaluation Deep Analysis

Discover evaluation code:

# Find evaluation scripts/functions
find . -name "eval*.py" -o -name "*evaluate*.py" -o -name "test*.py" 2>/dev/null | grep -v venv | grep -v __pycache__

# Extract metrics used
grep -rn "accuracy\|precision\|recall\|f1\|auc\|roc\|confusion\|mse\|mae\|loss" --include="*.py" . 2>/dev/null |
  grep -v venv | head -30

# Find metric computation
grep -rn "sklearn\.metrics\|torchmetrics\|tf\.keras\.metrics" --include="*.py" . 2>/dev/null | grep -v venv | head -15

# Check for saved evaluation results
find . -name "*results*.json" -o -name "*metrics*.json" -o -name "*eval*.json" 2>/dev/null | head -5
cat results.json metrics.json evaluation_results.json 2>/dev/null | head -30

Cross-reference with documentation:

• Compare documented metrics vs actual evaluation code
• Check if benchmark results are up-to-date
• Verify evaluation methodology matches implementation

5.7 Model Deployment Deep Analysis

Discover deployment configuration:

# Find deployment files
ls -la deploy/ deployment/ serving/ inference/ 2>/dev/null
find . -name "Dockerfile*" -o -name "docker-compose*" -o -name "*deploy*" -o -name "*serve*" 2>/dev/null |
  grep -v node_modules | head -15

# Find inference code
grep -rn "def predict\|def inference\|@app\.route\|@api\|FastAPI\|Flask" --include="*.py" . 2>/dev/null | grep -v venv |
  head -15

# Check for model serving configs
cat serve.yaml serving.yaml deployment.yaml kubernetes/*.yaml 2>/dev/null | head -50

# Find hardware requirements
grep -rn "cuda\|gpu\|device\|cpu\|memory" --include="*.py" --include="*.yaml" --include="*.yml" . 2>/dev/null |
  grep -v venv | head -15

Cross-reference with documentation:

• Compare documented deployment vs actual configuration
• Verify inference requirements match code
• Check if serving infrastructure is accurate

Step 6: Validate Existing Architecture Document Structure

If docs/architecture.md exists, validate its structure.

Check H1 Title

head -5 docs/architecture.md
grep "^# " docs/architecture.md | head -1

Expected: # Architecture Design (exactly this)

Check H2 Sections

grep "^## " docs/architecture.md

For Standard projects, must start with (in order):

## Table of Contents
## Architecture diagram
## Software units
## Software of Unknown Provenance
## Critical algorithms
## Risk controls

For ML/DL projects, must start with (in order):

## Table of Contents
## Datasets
## Data Preprocessing
## Data Splits
## Model Architecture
## Model Training
## Model Evaluation
## Software of Unknown Provenance
## Risk controls
## Model Deployment

Additional H2 sections may appear after the required ones.

Check Table of Contents Links

# Extract TOC links
grep -E "^\s*-\s*\[.*\]\(#" docs/architecture.md

Verify each link resolves to an actual heading in the document.

Step 7: Generate Comprehensive Accuracy Report

After deep analysis, provide a detailed report:

Report Format

## Architecture Documentation Review Report

### Repository Info
- **Organization:** {org}
- **Repository:** {repo}
- **Project Type:** {standard/ml_dl}
- **Document Status:** {exists/missing}
- **Last Doc Update:** {date}
- **Last Code Update:** {date}
- **Documentation Freshness:** {CURRENT/STALE - code changed since last doc update}

### Structure Checks
- [ ] H1 title "# Architecture Design": {PASS/FAIL - found: "{actual}"}
- [ ] Required H2 sections present: {PASS/FAIL}
- [ ] Section order correct: {PASS/FAIL}
- [ ] Table of Contents links valid: {PASS/FAIL}

### Content Accuracy Checks

#### {For Standard: "Architecture Diagram" / For ML: "Datasets"}
- **Status:** {PASS/FAIL/NEEDS UPDATE/MISSING}
- **Issues:**
  - {Specific issue 1}
  - {Specific issue 2}
- **Discovered in code:** {what was actually found}
- **Documented:** {what's currently in docs}

{Repeat for each section}

#### Software of Unknown Provenance
- **Status:** {PASS/FAIL/NEEDS UPDATE}
- **Total dependencies in code:** {n}
- **Documented dependencies:** {n}
- **Missing from docs:** {list}
- **In docs but not in code:** {list}
- **Version mismatches:** {list}
- **Missing licenses:** {list}

### Summary
- **Sections accurate:** {n}/{total}
- **Sections need update:** {n}
- **Sections missing:** {n}
- **Critical issues:** {list of high-priority fixes}

### Proposed Changes
{Show exact changes needed with before/after for each section}

Ask the user before making changes:

"I found the following issues with docs/architecture.md. Would you like me to fix them?"

Step 8: Create or Update Architecture Document

If Creating New Document

First create the docs directory if needed:

mkdir -p docs

Standard Project Template

# Architecture Design

## Table of Contents

- [Architecture diagram](#architecture-diagram)
- [Software units](#software-units)
- [Software of Unknown Provenance](#software-of-unknown-provenance)
- [Critical algorithms](#critical-algorithms)
- [Risk controls](#risk-controls)

## Architecture diagram

{Include or reference architecture diagram - create if missing}

![Architecture Diagram](./images/architecture.png)

### System Overview

{High-level description based on discovered modules and their interactions}

### Component Interactions

{Description of how components interact - based on imports/dependencies analysis}

## Software units

{For each discovered module:}

### {Module Name}

**Purpose:** {Extracted from docstring or inferred from code}

**Location:** `{actual/path/to/module}`

**Key Components:**

- `{ClassName}`: {description from docstring}
- `{function_name}`: {description from docstring}

**Internal Dependencies:**

- {Other modules this depends on}

**External Dependencies:**

- {Third-party packages used}

## Software of Unknown Provenance

| Package | Version | License | Purpose |
|---------|---------|---------|---------|

{For each dependency from lock file:} | {name} | {exact_version} | {license} | {inferred purpose} |

### Critical Dependencies

{Dependencies that are central to the application's functionality}

### Security-Sensitive Dependencies

{Dependencies handling crypto, auth, network, etc.}

## Critical algorithms

{For each discovered algorithm:}

### {Algorithm/Function Name}

**Purpose:** {From docstring or inferred}

**Location:** `{actual/path/to/file}:{line_number}`

**Implementation:**
{Brief description of how it works}

**Complexity:** {If documented or inferrable}

**Security Considerations:** {If applicable}

## Risk controls

### Security Measures

{Based on discovered security patterns:}

- **Authentication:** {Discovered auth mechanisms}
- **Authorization:** {Discovered authz patterns}
- **Input Validation:** {Discovered validation}
- **Encryption:** {Discovered crypto usage}

### Error Handling

{Based on discovered error handling patterns}

### Logging & Monitoring

{Based on discovered logging patterns}

### Failure Modes

| Failure Mode | Impact | Mitigation |
|--------------|--------|------------|
| {Inferred from error handling} | {Impact} | {Mitigation} |

ML/DL Project Template

# Architecture Design

## Table of Contents

- [Datasets](#datasets)
- [Data Preprocessing](#data-preprocessing)
- [Data Splits](#data-splits)
- [Model Architecture](#model-architecture)
- [Model Training](#model-training)
- [Model Evaluation](#model-evaluation)
- [Software of Unknown Provenance](#software-of-unknown-provenance)
- [Risk controls](#risk-controls)
- [Model Deployment](#model-deployment)

## Datasets

### Data Sources

| Dataset | Source | Size | Format |
|---------|--------|------|--------|

{For each discovered dataset:} | {name} | {source if found} | {actual size} | {format} |

### Data Description

{Based on discovered dataset classes and data files}

**Features:**
{Extracted from data loading code}

**Labels:**
{Extracted from data loading code}

### Data Statistics

{Based on actual data file analysis}

## Data Preprocessing

### Preprocessing Pipeline

{Based on discovered preprocessing code:}

1. **{Step from code}**: {Description}
  - Implementation: `{file}:{function}`
  - Parameters: {extracted parameters}

### Data Transformations

| Transformation | Purpose | Implementation |
|----------------|---------|----------------|

{For each discovered transform:} | {transform_name} | {from docstring} | `{file}:{line}` |

### Data Augmentation

{Based on discovered augmentation code}

## Data Splits

### Split Configuration

| Split | Ratio | Size | Method |
|-------|-------|------|--------|
| Training | {from code}% | {n} samples | {method} |
| Validation | {from code}% | {n} samples | {method} |
| Test | {from code}% | {n} samples | {method} |

### Split Implementation

**Location:** `{file}:{line}`

**Method:** {random/stratified/temporal/custom}

**Random Seed:** {if found}

## Model Architecture

### Architecture Overview

{Based on discovered model class}

**Model Type:** {CNN/RNN/Transformer/etc.}

**Framework:** {PyTorch/TensorFlow/etc.} v{version}

### Architecture Diagram

{Generate or reference based on model structure}

### Layer Specifications

| Layer | Type | Parameters | Output Shape |
|-------|------|------------|--------------|

{For each layer discovered in model:} | {layer_name} | {layer_type} | {params} | {shape if inferrable} |

### Model Configuration

**Location:** `{model_file}:{line}`

~~~python
{Actual model class signature and key layers}
~~~

### Input/Output Specifications

- **Input:** {shape, dtype from code}
- **Output:** {shape, dtype from code}

## Model Training

### Training Configuration

| Parameter | Value | Source |
|-----------|-------|--------|
| Optimizer | {actual optimizer} | `{file}:{line}` |
| Learning Rate | {actual lr} | `{file}:{line}` |
| Batch Size | {actual batch_size} | `{file}:{line}` |
| Epochs | {actual epochs} | `{file}:{line}` |
| Loss Function | {actual loss} | `{file}:{line}` |
| LR Scheduler | {if found} | `{file}:{line}` |

### Training Script

**Location:** `{training_script}`

### Training Procedure

{Based on actual training loop analysis}

### Checkpointing

{Based on discovered checkpoint saving code}

## Model Evaluation

### Evaluation Metrics

| Metric | Implementation | Latest Value |
|--------|----------------|--------------|
| {metric_name} | `{file}:{line}` | {from results file if exists} |

### Evaluation Script

**Location:** `{eval_script}`

### Benchmark Results

{From discovered results files}

| Dataset | Metric | Value | Date |
|---------|--------|-------|------|
| {dataset} | {metric} | {value} | {date} |

## Software of Unknown Provenance

| Package | Version | License | Purpose |
|---------|---------|---------|---------|
| {name} | {exact_version} | {license} | {purpose} |

### ML Framework Stack

| Framework | Version | Role |
|-----------|---------|------|
| {framework} | {version} | {role} |

### Data Processing Stack

| Package | Version | Role |
|---------|---------|------|
| {package} | {version} | {role} |

## Risk controls

### Model Risks

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| Model drift | {assess} | {assess} | {from code} |
| Data leakage | {assess} | {assess} | {from code} |
| Overfitting | {assess} | {assess} | {from code} |

### Data Risks

{Based on data handling code analysis}

### Operational Risks

{Based on deployment code analysis}

## Model Deployment

### Deployment Architecture

{Based on discovered deployment configs}

### Inference Implementation

**Location:** `{inference_file}`

**Entry Point:** `{function/endpoint}`

### Hardware Requirements

| Requirement | Specification | Source |
|-------------|---------------|--------|
| GPU | {from code} | `{file}` |
| Memory | {from code/config} | `{file}` |
| Storage | {estimated} | - |

### Serving Configuration

{From discovered serving configs}

### Monitoring

{Based on discovered monitoring/logging code}

Validation Checklist

Before completing, verify:

• H1 title is exactly # Architecture Design
• All required H2 sections present in correct order
• Table of Contents links all work
• All documented modules exist in codebase
• All codebase modules are documented
• Dependency versions match lock files exactly
• All dependencies have licenses documented
• File paths in docs point to actual files
• For ML/DL: Hyperparameters match actual code
• For ML/DL: Model architecture matches implementation
• For ML/DL: Metrics match evaluation code
• Risk controls reflect actual security measures

Step 9: Run Linters

After making changes to docs/architecture.md, run the linters skill to ensure the file passes all markdown linting rules:

/co-dev:run-linters

Fix any linting errors before considering the task complete.

Important Rules

1. Never fabricate information - Only document what actually exists in the code
2. Include file:line references - Help readers find implementations
3. Use exact versions - From lock files, not approximate versions
4. Verify all paths - Every file path must exist
5. Never remove existing content - Only add missing sections or fix inaccuracies
6. Preserve custom sections - Additional H2/H3 sections after required ones should be kept
7. Ask before modifying - Always show proposed changes and get user approval
8. Flag stale documentation - Warn if code changed significantly since last doc update
9. Document security dependencies - SOUP handling crypto/auth needs extra attention
10. Keep metrics current - If evaluation results exist, include latest values
11. Run linters after changes - Always run /co-dev:run-linters after modifying docs/architecture.md