gg-skill-architecture

GG-SKILL-ARCHITECTURE — Production-Grade Architecture Generator

An architecture that cannot drive gg-skill-specs without additional input is not done.

The full output schema (sections 1–15 with templates) is in references/schema.md — read it when writing Phase 3.

---

Input Modes

Mode	Trigger	What happens
Discovery	PATH only	Read PRD → adversarial review → write architecture.md
Enhancement	-f PATH -enh	Audit existing architecture.md → produce additive architecture-enhancement.md
Apply	-f PATH -apply	Enhancement + auto-resolve TBDs + re-validate in one pass
Autoupdate	-f PATH -update	Re-audit against current dep-tree.md / PRD-patched.md — refresh Agent Status Block only
Output	-o PATH	Custom output path for architecture.md

All generated content must be written in English.

---

Workflow Position

/gg-skill-prd -apply
      ↓
   PRD-patched.md   (confidence ≥ 0.8, ready_for_architecture: true)
      ↓
/gg-skill-architecture PRD-patched.md
      ↓
   architecture.md  (confidence ≥ 0.8, ready_for_specs: true)
      ↓
/gg-skill-specs N    (per phase)

Pre-flight check: Before running, verify that PRD-enhancement.md (if it exists) has ready_for_architecture: true. If it is false, stop and tell the user:

⚠ PRD is not ready for architecture (ready_for_architecture: false).
Run: /gg-skill-prd -f PRD.md -apply first.

---

Phase 0 — Context Check

Before reading the PRD, load all available context silently:

File	What to extract
dep-tree.md	Existing modules, high-coupling zones, already-built components
PRD-enhancement.md	confidence_score, phases_in_codebase, blocking_issues still open
architecture.md	If it exists → Enhancement mode (see below)

If architecture.md already exists and -enh / -apply was NOT specified:

⚠ architecture.md already exists at {path}.
Running Enhancement mode to avoid overwriting existing decisions.
Use -apply to auto-resolve TBDs, or pass -o to write a new file.

dep-tree.md usage:

• [BUILT] = module already implemented → do not re-architect it
• High fan-in/fan-out nodes → flag as [RISK] in related ADRs
• Modules in dep-tree but absent from PRD → flag as drift in Agent Status Block
• Do NOT generate architectural decisions solely from dep-tree.md — it maps dependencies, not intent

---

Phase 1 — PRD Analysis

Read the PRD at $ARGUMENTS. Extract and internalize:

PRD Section	What to extract
Executive Summary	Scale targets, success KPIs, constraints
Target Users	Concurrent users, device types, geography
MVP Scope	Features that drive architectural decisions
Feature Specifications	Data flows, real-time needs, async jobs
Technical Architecture (if present)	Stated stack choices, ADR-lite decisions
Data Models	Entities, relationships, critical constraints
Non-Functional Requirements	Latency, uptime, scale targets with values
Security & Compliance	Auth strategy, compliance requirements, threat model
Phase Roadmap	What must be built per phase

If the file does not exist or is unreadable: stop and tell the user with the exact path tried.

---

Phase 2 — Adversarial Architecture Review

Before writing a single line of architecture, run this internal review.

Adopt the gg-socrate posture: anti-sycophancy, steelman, no vagueness. Every weakness found must be resolved in the architecture — not noted and left open.

2.1 — Decision Challenges

Challenge	What it catches
"Is this DB choice driven by actual data access patterns, or familiarity?"	Cargo-culting
"What breaks at 10× current load — specifically, which component fails first?"	Premature scalability gaps
"Is this service boundary justified by team ownership or deployment independence, or just decomposition for its own sake?"	False microservices
"What is the single component whose failure takes down the entire system?"	SPOF not mitigated
"Which ADR says TBD without listing two alternatives and their trade-offs?"	Blocked architecture decisions
"Which component calls which — is any fan-out > 4?"	Coupling hot spots
"Is there a queue / async handoff here that could fail silently?"	Silent failure modes
"Does the auth strategy handle token revocation, not just issuance?"	Incomplete security design
"Which external dependency has no fallback strategy?"	Single external SPOF
"Is the data model normalized enough to avoid update anomalies, but not so normalized it creates N+1 query traps?"	Schema design issues

2.2 — Scalability Envelope

For each core component, answer:

• What is the bottleneck at 10× stated load?
• Is it horizontally scalable? What prevents it?
• What data grows unboundedly without a pruning/archiving strategy?

2.3 — Security Architecture Audit

• Is authentication and authorization separated?
• Is the session token store separate from the application DB?
• Is there input validation at the API boundary (not just the DB layer)?
• Are all secrets injected via environment (not hardcoded)?
• Is the rate-limiting strategy per-IP AND per-user (not just one)?

Rule: Do not proceed to Phase 3 with a SPOF that has no mitigation, a TBD ADR without alternatives, or an NFR without an architectural response.

---

Phase 3 — Write architecture.md

Read references/schema.md for the complete output template (sections 1–15).

Output file: path specified by -o, or architecture.md in the same directory as the PRD.

---

Phase 4 — Architecture Validation Gate

The architecture is not complete until ALL of the following pass.

Structural completeness (6 criteria)

• Every component from Phase 1 has a Section 4 entry with responsibility, tech, interfaces, failure mode
• Every entity used in Phase 1 user stories is modeled in Section 5
• System Context Diagram shows all external dependencies from the PRD
• Every external dependency has a fallback or an explicit accepted-risk statement
• Section 11 (ADRs) covers: DB choice, auth strategy, deployment model, API style
• Every TBD ADR lists ≥ 2 alternatives with trade-offs and a review date

Decision quality (3 criteria)

• Every tech stack choice is marked [DECIDED] / [RECOMMENDED] / [TBD] — no unmarked choices
• No [RECOMMENDED] contradicts a [DECIDED] from the PRD without an ADR explaining the divergence
• Rate limiting is per-IP AND per-user

NFR coverage (2 criteria)

• Every NFR from PRD Section 8 has an architectural response in Section 12
• Every NFR architectural response names a specific component

Security (1 criterion)

• Section 9 addresses all threats from the PRD Threat Model with specific mitigations

Output of this gate (in chat, not in architecture.md):

## Architecture Validation
- ✅ Structural completeness: X/6 criteria
- ✅ Decision quality: X/3 criteria
- ✅ NFR coverage: X/2 criteria
- ✅ Security: X/1 criteria

[Any ❌ items listed with what's missing and how to fix]

confidence_score: 0.XX (threshold: 0.80)
[✅ Ready for /gg-skill-specs | ⚠ Resolve N blocking issues first]

---

Enhancement Mode (-f PATH -enh)

When an existing architecture.md is provided:

1. Read the architecture silently
2. Run the Recognition Pass — identify what is already senior-grade (do not revisit)
3. Run the Gap Audit against the Validation Gate
4. Output: architecture-enhancement.md (additive only — never modify the original)

Sections in order: header → Agent Status Block (Section 15 schema) → What Is Already Senior-Grade → Blocking Gaps → Should Fix → Accepted Weaknesses → Next Action Plan (ordered by blocking priority, ending with /gg-skill-specs 1 when all blocking gaps are resolved).

---

Apply Mode (-f PATH -apply)

Apply mode runs Enhancement → auto-resolves TBDs using FULL/SKELETON/BLOCKED source resolution → re-runs Validation Gate → loops until ready_for_specs: true or hits an unresolvable gap.

Source resolution (before any injection):

FOR EACH TBD / gap identified:
  SOURCES (in priority order):
    1. PRD-patched.md     → most complete — use if PRD section covers it
    2. PRD.md             → fallback if PRD-patched not present
    3. dep-tree.md        → for component names and existing structure only
    4. architecture.md    → existing decisions (for Enhancement mode)

  IF source found with full detail  → quality: FULL
  IF source only gives structure    → quality: SKELETON → inject [TBD] placeholder
  IF no source                      → quality: BLOCKED  → skip, list for human input

Apply rules:

• Never modify the original architecture.md
• Output: architecture-patched.md (or path from -o)
• Mark all injected content with <!-- injected by gg-skill-architecture -apply -->
• Never invent business rules, KPI targets, or compliance requirements — mark [TBD — requires owner input]
• A SKELETON injection does NOT clear a blocking issue
• Max 2 auto-patch iterations — if blocking issues remain after pass 2, stop and report

After Apply output (in chat):

## Apply Mode — Result

Patched: {output path}
Passes: {N}

Before:  {X}/12 ✅  ({blocking} blocking, {should} should-fix)
After:   {Y}/12 ✅  ({blocking} blocking, {should} should-fix)

Patch report:
  ✅ Added (FULL):    {section}, {section}, ...
  ⚠  Partial (SKELETON): {section} — [TBD] markers inserted
  ❌ Failed:          {section} — reason: {no source | requires human input}

confidence_score: {before} → {after}

{IF ready_for_specs}
Next: /gg-skill-specs 1

{IF blocking_issues remain}
⚠ {N} blocking issues require human input — see above.

---

Autoupdate Mode (-f PATH -update)

Re-audits the architecture against the current state of the codebase without rewriting any content.

What it reads:

• architecture.md (or architecture-patched.md if present)
• dep-tree.md (current)
• PRD-patched.md (if present — checks for new NFRs or phases since last run)
• architecture-enhancement.md (if present — updates its Agent Status Block only)

What it updates (YAML block only):

• updated_at → current datetime
• drift_from_dep_tree → recompute from current dep-tree.md
• phase_coverage[*] → recheck per phase
• tbd_count → recount [TBD] markers in current architecture file
• blocking_issues → remove any that are now resolved
• confidence_score → recompute all 4 dimensions + global
• next_action → update based on new status

What it does NOT touch:

• The gap analysis text (B-N, S-N items) — human-authored, immutable
• architecture.md or architecture-patched.md content

Autoupdate output (in chat):

## Autoupdate — {datetime}

Changes detected:
  drift_from_dep_tree: {N changes}
  phase_coverage.phase_N: blocked → ready
  tbd_count: {before} → {after}
  confidence_score: {before} → {after}

{IF ready_for_specs changed to true}
✅ Architecture now ready for specs. Next: /gg-skill-specs 1

{IF still blocked}
⚠ {N} blocking issues remain — see architecture-enhancement.md

---

Output Confirmation (in chat, after writing)

After writing the file:

1. Confirm the output path
2. Run the Validation Gate and show the result
3. List all [TBD] decisions that need team input (with phase-blocking impact)
4. List all [RECOMMENDED] choices that deviate from the PRD's stated stack
5. Show confidence_score and whether the threshold is met
6. Suggest immediate next steps:
   • If confidence_score ≥ 0.8: Next: /gg-skill-specs 1
   • If TBDs remain: ⚠ Resolve {N} TBD ADRs before /gg-skill-specs — {ADR-00X} blocks Phase {N}

---

DO / DON'T

DO:

• Map every architectural decision back to a PRD requirement or NFR
• Mark TBD decisions explicitly with ≥ 2 alternatives and trade-offs
• Include real performance numbers from the PRD's NFRs
• Name the specific component responsible for each NFR response
• Use [BUILT] for components already in dep-tree — don't re-architect what works
• Flag high coupling (fan-out > 4) as [RISK] in the related ADR
• Write failure modes for every component

DON'T:

• Over-engineer for scale not stated in the PRD
• Invent a tech stack if PRD says TBD — write TBD with ≥ 2 options and trade-offs
• Skip ADRs for obvious choices — obvious to you is not obvious to the team in 6 months
• Generate a monolith architecture for a PRD that clearly needs distributed components (or vice versa)
• Mark an NFR as covered without naming the specific architecture component
• Accept "the system should be secure" as a security section — it must reference the PRD threat model

---

Example Invocations

# Discovery — generate architecture from PRD
/gg-skill-architecture /home/project/PRD-patched.md

# Custom output path
/gg-skill-architecture /home/project/PRD-patched.md -o /home/project/docs/architecture.md

# Harden existing architecture
/gg-skill-architecture -f /home/project/architecture.md -enh

# Auto-resolve TBDs
/gg-skill-architecture -f /home/project/architecture.md -apply

# Refresh status after dep-tree regeneration
/gg-skill-architecture -f /home/project/architecture.md -update