feat: add software-architecture-analysis skill #4

Merged

magnus merged 1 commit from feat/software-architecture-analysis-skill into main

2026-05-21 22:39:15 -04:00

jasper commented

2026-05-21 22:36:38 -04:00

Contributor

Summary

7-phase methodology for reverse-engineering codebases into clean-room design documents. Core IP: the interface extraction pattern (Phase 3b) for designing storage provider abstractions from codebase analysis.

Files

software-architecture-analysis/
├── SKILL.md                                             # 228 lines
└── references/
    └── interface-extraction-pattern.md                   # 79 lines — worked example

The Seven Phases

Clone + Map — shallow clone, directory structure analysis
Find Key Files — sort by line count, read top 15-25 files
Map Architecture — Mermaid diagrams, data flow, privacy boundaries
3b. Interface Extraction — catalog storage ops, identify boundary leaks, design provider contract, validate with two-provider proof
Feature Inventory — surface every user-facing feature
Clean-Room Spec — architecture-level descriptions only, zero code samples
Break Constraints — redesign for local-first, privacy-first, self-hosted
Post-Delivery QA — link integrity, diagram rendering, contamination check

What makes this novel

The interface extraction pattern (Phase 3b) teaches how to find the implicit contract a codebase makes with its storage layer, then formalize it into a swappable provider abstraction
The clean-room discipline is a built-in workflow step, not an afterthought
The breaking-constraints framework makes architecture comparison a structured process rather than vibes
The worked example uses a real open-source project (cashew thought-graph, MIT)

Signed-off-by: Jasper magnus@groktop.us

## Summary 7-phase methodology for reverse-engineering codebases into clean-room design documents. Core IP: the interface extraction pattern (Phase 3b) for designing storage provider abstractions from codebase analysis. ## Files ``` software-architecture-analysis/ ├── SKILL.md # 228 lines └── references/ └── interface-extraction-pattern.md # 79 lines — worked example ``` ## The Seven Phases 1. **Clone + Map** — shallow clone, directory structure analysis 2. **Find Key Files** — sort by line count, read top 15-25 files 3. **Map Architecture** — Mermaid diagrams, data flow, privacy boundaries 3b. **Interface Extraction** — catalog storage ops, identify boundary leaks, design provider contract, validate with two-provider proof 4. **Feature Inventory** — surface every user-facing feature 5. **Clean-Room Spec** — architecture-level descriptions only, zero code samples 6. **Break Constraints** — redesign for local-first, privacy-first, self-hosted 7. **Post-Delivery QA** — link integrity, diagram rendering, contamination check ## What makes this novel - The interface extraction pattern (Phase 3b) teaches how to find the *implicit contract* a codebase makes with its storage layer, then formalize it into a swappable provider abstraction - The clean-room discipline is a built-in workflow step, not an afterthought - The breaking-constraints framework makes architecture comparison a structured process rather than vibes - The worked example uses a real open-source project (cashew thought-graph, MIT) Signed-off-by: Jasper <magnus@groktop.us>

jasper added 1 commit

2026-05-21 22:36:38 -04:00

feat: add software-architecture-analysis skill 941d5c36dc

7-phase methodology for reverse-engineering codebases and producing
clean-room design documents under new constraints. Core workflow:

Phase 1: Clone & map repository structure
Phase 2: Find key architectural files (sort by line count)
Phase 3: Map architecture with Mermaid diagrams
Phase 3b: Extract implicit storage/provider contracts (DAO design)
Phase 4: Inventory feature surface
Phase 5: Write clean-room specification (no code contamination)
Phase 6: Break constraints (local-first, privacy-first redesign)
Phase 7: Post-delivery QA (link integrity, diagram rendering)

Includes a full worked example of the interface extraction pattern
(references/interface-extraction-pattern.md) using the cashew
thought-graph library — demonstrating all five steps from philosophy
reading through two-provider proof concept.

Signed-off-by: Jasper <magnus@groktop.us>

magnus merged commit eec8c7e851 into main

2026-05-21 22:39:15 -04:00

magnus referenced this pull request from a commit

2026-05-21 22:39:17 -04:00

Merge pull request 'feat: add software-architecture-analysis skill' (#4) from feat/software-architecture-analysis-skill into main