fresh-arch · diff
git:20260810.3750f6a to git:20261003.9d332e2
15 added, 14 removed. Audit A to A.
---
name: fresh-arch
- description: Architecture design reasoned forward from requirements. Use when the user wants a fresh-mind design pass — "design an architecture for", "how would you build", "redesign from scratch" — or when repeated follow-up patches accumulate on the same module. Repeated follow-up patches landing on the same module (~3rd) → stop patching, invoke this skill to re-derive from the full requirement set.
+ description: >
+ Re-derive a fresh-mind architecture design reasoned forward from requirements. Use this skill before applying follow-up patches, feature changes potentially shift optimal design, or refactorization on a pre-existing codebase. Does not apply to empty codebase or new project.
---
- Design an architecture for the topic above by reasoning forward from requirements. If a codebase exists, you may Read/Grep it — but only as evidence to evaluate, not as a frame to fit the new design into.
+ Design an architecture for the user request by reasoning forward from requirements, not anchoring pre-existing design or conversation.
+ **Steps**
+
+ 1. Explore pre-existing codebase ONLY as evidence to understand current situation, not as a frame to fit the new design into.
+ 2. Analysis user intent: what are the new features they want to have (add), what existing features they no longer require (delete), what existing features are out of scope (keep).
+ 3. Clarify what the system must do (not how), and must not do.
+ 4. Re-derive implementation from the full requirement set, without refering existing code.
+ 5. Compare with pre-existing implementation, list what are now stale (must be replaced or deleted).
+ 6. Implement without anchoring stale design.
+
**Mindset**
Catch yourself in any of these and stop — they are migration concerns smuggled in as design concerns:
- "the current code does X, so the new design should look similar"
+ - "X is a pre-existing feature so it must survives"
- "we need to stay backward-compatible with X"
- "let's stick to the existing module boundaries / pattern / abstractions"
- "let's not be too aggressive / disruptive / far from what the team knows"
- "X is already wired up, so reuse it"
-
- If a current pattern survives, it survives on merit — because it is the right answer when reasoned forward from requirements — not because it is already there.
-
- **Checklist**
-
- Think through these points mentally:
+ - "X is in codebase, so the user must still want it"
- - [ ] **Problem** — 1-3 lines, what the system must do (not how).
- - [ ] **Components** — 3-7 boxes, each with a one-sentence responsibility. Justify why these and not fewer/more.
- - [ ] **Contracts** — interfaces / message shapes between components.
- - [ ] **Data & state** — what's stored where, consistency model, lifecycle.
- - [ ] **Rejected alternatives** — at least one different shape you considered and why this one wins.
- - [ ] **Critique of the current design** *(if a codebase exists)* — judged against the design above. What the current system gets wrong, what it accidentally gets right, what is load-bearing vs. incidental. Not a migration plan; migration is a separate problem.
+ If a current pattern survives, it survives only when it is the sane answer when reasoned forward from requirements — not because it is already there.