DavidROliverBA/ArchitectKB / .claude/skills/architecture-report
architecture-report
Verified/architecture-report Skill
Generate comprehensive architecture reports for stakeholder communication, audits, and governance.
When to Use This Skill
Use /architecture-report when you need to create:
- Executive architecture briefings
- Formal architecture reviews (security, compliance, technical)
- Architecture audit reports
- Governance compliance documentation
- Technical due diligence reports
- Architecture portfolio status reports
Usage
/architecture-report <scope> [audience] [options]
Parameters
| Parameter | Description | Required |
|---|---|---|
scope | What to report on (system, program, enterprise, all) | Yes |
audience | Who is reading (executive, technical, audit, board) | Optional |
--period | Time period (week, month, quarter, year, all-time) | Optional |
--format | Output format (markdown, word, pdf, presentation) | Optional |
Report Types
1. System Architecture Report
/architecture-report system:DataPlatform --audience technical
Scope: Single system (DataPlatform) with deep dive into:
- System description and purpose
- Technology stack and components
- Integrations and dependencies
- Performance metrics and SLAs
- Security and compliance posture
- Cost and operational metrics
- Architecture diagrams (C4 Level 2-3)
- Known issues and improvement backlog
- Roadmap and future evolution
2. Program Architecture Report
/architecture-report program:MyDataIntegration --audience executive
Scope: Program/Project with overview of:
- Program description and business case
- Systems involved and relationships
- Key architecture decisions (ADRs)
- Timeline and milestones
- Budget and spend tracking
- Risk status
- Critical dependencies
- Executive summary and recommendations
3. Enterprise Architecture Report
/architecture-report enterprise --audience board
Scope: Entire enterprise architecture covering:
- Enterprise architecture overview
- System landscape and classifications
- Critical dependencies and single points of failure
- Technology standards and compliance
- Financial summary (cost by system, total TCO)
- Architecture maturity assessment
- Strategic initiatives and roadmap
- Risk summary (technology, organizational, financial)
- Governance and decision-making overview
4. Architecture Review Report
/architecture-report system:DataPlatform --audience audit
Scope: Formal architecture review for:
- Security posture assessment
- Compliance status (SOX, ISO, GDPR, HIPAA, etc.)
- Data protection and privacy
- Disaster recovery readiness
- Performance and scalability
- Operational excellence
- Cost optimization
- Recommendations and action items
Workflow
Phase 1: Define Report Scope
User specifies:
-
What to report on
- Single system (system:DataPlatform)
- Program (program:MyDataIntegration)
- Domain (domain:data, domain:integration)
- All systems (enterprise)
-
Who is the audience (optional)
executive- CFO/CEO level, focus on business valuetechnical- Architects/engineers, focus on designaudit- Security/compliance, focus on controlsboard- Board of directors, focus on risk/strategyall- Comprehensive report for all audiences
-
Time period (optional)
- Current state only
- Quarter-over-quarter changes
- Year-over-year trends
- Historical evolution
-
Output format (optional)
- Markdown (for vault)
- Word/PDF (for distribution)
- PowerPoint (for presentations)
- HTML (for web publishing)
Phase 2: Gather Data
The skill:
-
Collects system information
- System properties (type, owner, criticality, cost)
- Technology stack details
- Integration landscape
-
Extracts architecture documentation
- HLD/LLD documents
- Architecture decisions (ADRs)
- Scenarios and roadmaps
- C4 diagrams
-
Calculates metrics
- System inventory counts
- Cost aggregations
- Dependency counts
- Risk scores
-
Gathers compliance data
- Security status
- Compliance frameworks
- Data classification
- Control assessments
Phase 3: Generate Report
Creates comprehensive report with:
- Executive summary
- Detailed analysis sections
- Diagrams and visualizations
- Metrics and KPIs
- Risk assessment
- Recommendations
- Appendices (detailed data)
Phase 4: Output
Generates report in requested format:
- Markdown (for vault storage and updates)
- PDF (for formal distribution and archival)
- PowerPoint (for presentations)
- Word (for collaborative editing)
Report Sections
Executive Summary (All Reports)
1-2 page overview containing:
Architecture Status Report: DataPlatform Data Integration Platform
═════════════════════════════════════════════════════════
Period: Q4 2025 (Oct-Dec 2025)
Reporting Date: 2026-01-14
EXECUTIVE SUMMARY
─────────────────
Current State: Stable and high-performing
Key Metrics: 99.95% availability, 450 pipelines, 150 TB data
Status: ✓ Green (All targets met)
Financial Impact:
• Annual cost: £1.8M
• Cost trend: +5%/year (within forecast)
• ROI: Positive (data volume +15% year-over-year)
Key Achievements:
1. Achieved 99.95% SLA (target: 99.95%)
2. Completed real-time SAP integration (50K events/day)
3. Reduced batch latency from 6h to 4.5h
4. Migrated 40 pipelines to Kubernetes
Risks & Concerns:
• Medium: Aging DataPlatform codebase needs modernization
• Low: Skills gap in Spark expertise
Next Quarter:
• Launch Snowflake Streaming integration
• Retire legacy Informatica pipelines
• Expand real-time capabilities
Section 1: System Overview
For each system in scope:
-
Basic Information
- Name, type, owner, business purpose
- Criticality, SLA, availability target
-
Technology Stack
- Languages, frameworks, databases
- Hosting infrastructure
- Key components
-
Deployment
- Infrastructure (AWS, on-prem, hybrid)
- Environments (dev, test, prod, dr)
- Data residency and compliance
-
Key Metrics
- Users/consumers
- Data volume
- Throughput
- Latency
Section 2: Architecture Decisions
Lists all ADRs related to scope:
- Decision title and status
- Rationale and alternatives considered
- Implementation status
- Recent updates
Section 3: Integrations & Dependencies
Shows integration landscape:
- All systems this system connects to
- Integration patterns (real-time, batch, API)
- Data flows and volumes
- Critical dependencies (what breaks if this system fails)
Created as visual diagram + table format.
Section 4: Performance & Reliability
Metrics and trends:
Performance Metrics (Last Quarter)
──────────────────────────────────
Availability: 99.95% (target: 99.95%) ✓
Latency (p99): 1.2 sec (target: <2 sec) ✓
Throughput: 450K evt/sec (target: 400K) ✓
Data Freshness: <30 sec (target: <1 min) ✓
Reliability Metrics
───────────────────
Incidents (P1/P2): 2 incidents (target: <3) ✓
MTTR: 45 min (target: <1 hour) ✓
Unplanned Downtime: 1.5 hours/year (target: <4 hours) ✓
Trend Analysis:
• Availability trending up (+0.05% vs last quarter)
• Latency stable (consistent 1.2 sec p99)
• No degradation despite 15% data volume growth
Section 5: Security & Compliance
Compliance status and controls:
Compliance Status
─────────────────
SOX Compliance: ✓ Compliant (last audit: 2025-11-01)
ISO 27001: ✓ Certified (expires: 2027-03-15)
GDPR Data Rights: ✓ Implemented (right to delete, access)
HIPAA: N/A (not health data)
PCI-DSS: ✓ Compliant (if payment data processed)
Security Controls
─────────────────
Encryption at Rest: ✓ AES-256 (AWS KMS)
Encryption in Transit: ✓ TLS 1.3
Access Control: ✓ RBAC + MFA
Audit Logging: ✓ CloudTrail + application logs
Data Classification: ✓ Confidential (PII, financial data)
Penetration Testing: ✓ Annual (last: 2025-10-15, clean)
Recent Findings:
• Critical: None ✓
• High: None ✓
• Medium: 2 (both mitigated)
• Low: 3 (documented for next release)
Remediation Status:
Medium 1: Pending patch release (ETA: 2026-02-01)
Medium 2: Working around, permanent fix planned Q2 2026
Section 6: Financial Analysis
Cost breakdown and trends:
Annual Cost Breakdown
─────────────────────
Infrastructure (AWS): £800K (44%)
• EC2 (Spark workers): £450K
• S3 storage: £200K
• RDS/Aurora: £100K
• Data transfer: £50K
Software & Licensing: £500K (28%)
• Apache Spark: £0 (open source)
• Kafka: £0 (open source)
• Airflow: £0 (open source)
• vendor support: £500K
Staffing: £500K (28%)
• 3 engineers (avg £166K)
• Dedicated on-call
─────────
Total Annual: £1.8M
Cost Trend:
• FY2024: £1.7M
• FY2025: £1.8M (+5.9%)
• FY2026 forecast: £1.9M (+5.6%)
Cost Drivers:
• Data volume growth (10 TB/day additional per year)
• Increased compute (more real-time pipelines)
• Stable staffing
Section 7: Roadmap & Future Evolution
Known initiatives and plans:
Q1 2026: Snowflake Streaming Integration
• Status: Approved, planning phase
• Benefit: Real-time analytics (30-sec lag)
• Cost: £35K setup, +£18K/year
• Risk: Medium (Snowflake connector still new)
Q2 2026: Retire Informatica Pipelines
• Status: In progress (2 of 8 pipelines migrated)
• Benefit: Cost savings £200K/year
• Cost: Migration effort (1 engineer, 6 months)
• Risk: Low (DataPlatform proven stable)
Q3 2026: Spark to Scala Migration
• Status: Planned
• Benefit: Performance +30%, type safety
• Cost: Rewrite 40 pipelines (3 engineers, 4 months)
• Risk: High (major codebase change)
Q4 2026+: ML/Advanced Analytics
• Status: Research phase
• Benefit: Predictive analytics, anomaly detection
• Cost: TBD (new ML team)
• Risk: High (new domain)
Section 8: Risk Assessment
Detailed risk analysis:
Risk Assessment Matrix
──────────────────────
Probability (vertical) vs Impact (horizontal)
Low Medium High Critical
Critical ●(2)
High ● ●(1)
Medium ●(3) ●
Low ●(4)
1. DataPlatform codebase complexity
Probability: Medium (technical debt accumulating)
Impact: High (difficult to enhance/maintain)
Mitigation: Spark to Scala migration (Q3 2026)
Owner: Chief Architect
2. Data volume growth outpaces infrastructure
Probability: High (10 TB/day growth trend)
Impact: Critical (performance degradation)
Mitigation: Snowflake Streaming (Q1 2026), right-sizing
Owner: Platform Lead
3. Skill gap in Spark expertise
Probability: Medium (2 engineers, high demand)
Impact: Medium (harder to onboard, maintain)
Mitigation: Internal training, hire specialist
Owner: Engineering Manager
4. AWS cost growth
Probability: Low (cloud discounts available)
Impact: Low (manageable with optimization)
Mitigation: Reserved instances, spot instances
Owner: Cloud Architect
Section 9: Recommendations
Prioritized action items:
Priority 1 (This Quarter - Q1 2026)
───────────────────────────────────
1. Approve and fund Snowflake Streaming integration
• Business value: Real-time analytics
• Effort: 4 engineers, 3 months
• Cost: £35K setup, +£18K/year
• Target go-live: 2026-04-30
2. Negotiate AWS volume discount
• Potential savings: £200K/year (3.8%)
• Effort: Finance + AWS team, 1 month
• No implementation risk
Priority 2 (Q2 2026)
───────────────────
3. Begin Informatica pipeline retirement
• Cost savings: £200K/year
• Effort: 1 engineer, ongoing
• Risk: Low (DataPlatform proven)
4. Hire Spark specialist engineer
• Salary: ~£85K
• Timeline: Immediate (6-week recruitment)
• Reduces skill gap and bus factor
Priority 3 (Q3 2026+)
────────────────────
5. Plan and execute Spark to Scala migration
• Timeline: 4 months
• Benefit: +30% performance, type safety
• Risk: High (major refactor)
• Decision needed: Cost/benefit analysis
Section 10: Appendices
Detailed data for reference:
- System metrics table (all systems in scope)
- Integration connectivity matrix (what connects to what)
- Technology inventory (all technologies used)
- Cost analysis spreadsheet (detailed breakdown)
- Compliance checklist (all frameworks and status)
- Contact directory (owners, architects, on-call)
- Glossary of terms (domain-specific terminology)
Report Customization
By Audience
The skill tailors content based on audience:
Executive Summary Only (5 pages):
/architecture-report enterprise --audience board --depth summary
Contains:
- 1-page executive summary
- Key metrics dashboard
- Financial summary
- Risk summary
- Strategic recommendations
Detailed Technical Report (30+ pages):
/architecture-report enterprise --audience technical --depth comprehensive
Contains:
- All sections with technical deep-dive
- Architecture diagrams (C4, data flows)
- Technology details and comparisons
- Performance analysis
- Optimization opportunities
Audit/Compliance Report (50+ pages):
/architecture-report system:SAP --audience audit --depth comprehensive
Contains:
- Compliance checklist
- Security controls inventory
- Risk assessment
- Audit findings
- Remediation tracking
- Evidence references
By Period
Show trends over time:
/architecture-report enterprise --period quarter
Compares current vs previous quarter with:
- Metrics trends
- Cost trends
- Risk status changes
- Initiative progress
Output Examples
Quick Summary (Markdown, 5 pages)
Architecture Report - DataPlatform Q4 2025.md (markdown format)
Embeds:
- Inline diagrams (Mermaid)
- Cost charts (Markdown tables)
- Risk matrix (Unicode text art)
- Links to related notes
Formal Report (PDF, 30+ pages)
Architecture Report - Enterprise 2026.pdf (professional PDF)
Includes:
- Cover page with date/reviewer info
- Table of contents
- Executive summary
- Detailed sections with headings/subheadings
- Professional diagrams and charts
- Page numbers and headers/footers
- Appendices with detailed data
Presentation Slides (PowerPoint)
Architecture Review - MyDataIntegration Program.pptx (presentation)
Includes:
- Title slide with date/presenter
- 1 slide per major section
- Diagrams and charts on each slide
- Notes for presenter
- Appendix slides with detailed data
Quality Indicators
All reports include quality metadata:
type: Page | Canvas | Dashboard
reportType: system | program | enterprise | audit
reportPeriod: Q4 2025
generatedDate: 2026-01-14
generatedBy: /architecture-report skill
audience: executive | technical | audit | board
dataFreshness: current # All data current
verified: true # All metrics verified
nextReview: 2026-04-14 # Recommended review date
Report Templating
Create custom report templates:
/architecture-report enterprise --template "Executive Board Review"
Templates store:
- Which sections to include
- Audience tailoring
- Branding/formatting
- Distribution list
- Review cycle
Automated Report Generation
Schedule recurring reports:
/architecture-report enterprise --schedule "monthly on the 15th" --store
Automatically generates:
- Monthly enterprise report (15th of each month)
- Quarterly review (month 1, 4, 7, 10)
- Annual comprehensive review (January)
Distributes to stakeholders via email.
Integration with Other Skills
The /architecture-report skill works with:
/diagram- Generate diagrams for report/system-sync- Sync data before report generation/cost-optimization- Include cost analysis section/impact-analysis- Include impact of planned changes
Next Steps
After generating report:
- Review for accuracy and completeness
- Distribute to stakeholders (via email, wiki, meetings)
- Schedule review meetings if needed
- Track recommendations (create tasks)
- Plan next report cycle
- Archive previous report (for historical comparison)
Invoke with: /architecture-report <scope>
Example: /architecture-report enterprise --audience board → Generates executive board briefing
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |