architecture-lens

Architecture Lens

Overview

A lightweight lens you wear while implementing — not a workflow. Two fire points: a pre-flight lens before you write a unit, and a post-diff audit before you commit. Between the two, TDD drives the work. The lens is deliberately light so you actually use it on every task, instead of skipping it because "this one's small."

When to Use

• Inside the IMPLEMENT step of a plan produced by superpowers:brainstorming + superpowers:writing-plans.
• Alongside superpowers:test-driven-development — TDD drives the red-green-refactor; the lens bookends it.
• Every implementation task in a multi-task plan executed via superpowers:subagent-driven-development or superpowers:executing-plans. One pre-flight per task, one post-diff audit per commit.

When NOT to Use

• Throwaway scripts, spikes, or one-off hotfixes.
• Cosmetic edits (whitespace, renames, comment fixes) — the lens has no signal for them.
• When the codebase needs restructuring, not new code. Use improve-code-architecture instead.
• When you have no plan yet. Run superpowers:brainstorming first — the lens is not a substitute for deciding what to build.

Relationship to improve-code-architecture

Default to this skill while implementing. improve-code-architecture is the escalation path, not the starting point.

improve-code-architecture is a restructuring workflow for codebases that already need surgery — ASK → DIAGNOSE → PLAN → CONFIRM → IMPLEMENT, with an 11-pattern reference. It is deliberately heavy.

architecture-lens is a per-task lens for preventing new rot while implementing. It is deliberately light.

If the lens surfaces a problem too deep to fix in the current diff, escalate to improve-code-architecture (see the Escalation section below). The two skills are designed to be used together: the lens catches drift; the workflow fixes accumulated drift.

The Five Qualities

Quality	What it means
Architecturally Aligned	Fits the existing seams — layering, bounded contexts, composition root. Does not introduce a new shape incompatible with neighbors.
Readable	A stranger grasps intent in 60 seconds. Names reveal purpose. No cleverness for its own sake.
Modular	One responsibility per unit. Clean interface. Consumers do not read internals.
Reusable	Explicit contract. No hidden globals. No import-time side effects. Usable in a test or a second caller without rewriting.
Maintainable	Safe to change one concern without ripple. Edge cases documented where non-obvious.

Testable is not on this list — superpowers:test-driven-development owns it. If you cannot unit-test a unit, the shape is wrong and that is a T1 finding.

T1 — Before You Implement

Fires once, at the start of an implementation task, after the plan has been written and before any test or code is written. Walk the prompts once; skip ones that are trivially answered; stop and re-plan if any one blocks.

• Where does this new unit live? Does it slot into an existing layer (domain, application, infrastructure, interface), or am I inventing a new one? If inventing one, justify it in a sentence.
• What is its single responsibility, in one sentence? If I cannot say it in one sentence without "and," I have the wrong boundary.
• What is the minimum surface area I need to expose? Private by default; widen only when a second caller actually arrives.
• What does it depend on? Are those dependencies injectable (passed in) or hard-coded (imported)? Prefer injectable for anything that touches I/O, the clock, randomness, or process config.
• Am I building an interface for a speculative second implementation? If yes, stop — wait for the second caller. An interface with one forever-implementation is dead weight.
• What existing pattern in this codebase does this most resemble? If nothing resembles it, that is a signal to ask why. Maybe the codebase already has a better home for it.
• What does the unit test look like? If I cannot sketch a unit test without a real DB, real HTTP, or a vendor SDK mock, the shape is wrong. Revisit before typing code.
• (Changes to existing code only): What contract am I preserving? What contract am I changing? Callers should not have to guess.

If any prompt reveals a problem the current plan did not anticipate, stop and raise it to the controller / user before writing code.

T3 — Before You Commit

Fires before every commit, not just the final one. Walk the diff against these prompts. If any prompt surfaces an issue, fix it in place and re-walk; or escalate (see below).

• Does this commit do one thing? If the message would need "and" to be accurate, split.
• Read the diff as a stranger. Can I state the intent in 60 seconds? If not, rename symbols or add a one-line comment on the non-obvious why (never the what).
• Any new interface with exactly one implementation? Delete it. Wait for the second caller.
• Any duplicated shape now appearing 3+ times? Extract. Rule of three.
• Any side effect — I/O, time, randomness, global mutation — inside a function that is or looks pure? Separate the effect from the decision.
• Any new module-level state (singleton, cached client wired from env at import time)? Move construction to the composition root.
• Any any / untyped boundary I added to make the compiler stop complaining? Replace with a real contract or an explicit unknown + parse.
• Does this diff change the architecture? If yes, does the plan anticipate it, or am I drifting? Drift is a re-plan moment, not a commit moment.

Escalation to improve-code-architecture

Escalate when:

• The fix for a T3 finding would ripple across 3+ files.
• I cannot name the hidden concern of a boundary I want to introduce — fails the "Pattern X hides concern Y so Z can change independently" test.
• The problem requires a new seam (layer, port, repository, event bus) that does not exist in the codebase yet.
• Two T3 audits in a row surface the same structural smell — that is a pattern, not a slip.

Handoff format. Stop implementation. Report to the controller / user with:

1. The symptom in one sentence.
2. Affected files (paths).
3. Suspected boundary that is missing or wrong.
4. Whether it blocks the current task or can be parked behind a ticket.

Then invoke improve-code-architecture.

Red Flags — STOP and Reconsider

• Skill "invoked" but no prompts actually considered — going through the motions. If this happens twice, the lens has become ritual; pause and calibrate.
• T3 audit "passed" but the commit still does two things. Split the commit; the audit missed a prompt.
• Escalation avoided because "I can fix it quickly," and the quick fix balloons. The criterion is objective (ripple across 3+ files), not vibe-based.
• Five qualities treated as boxes to tick instead of a lens to see through. The lens is not a score card.
• This skill growing stages and approval gates. It would then duplicate improve-code-architecture; trim instead.

Rationalization Table

Excuse	Reality
"This is only one file, the lens is overkill"	One file is where the next file's duplication starts. Run the lens.
"T1 duplicates planning"	T1 is not re-planning; it translates the plan into local decisions at the moment of typing.
"T3 duplicates code review"	Code review is someone else catching what you missed. T3 is catching it yourself first.
"Five qualities are too many to remember"	They are a lens, not a checklist. Use them to see, not to score.
"I already escalated once this sprint, that's enough"	Escalation is per-symptom, not per-period. Escalate again if the criteria hit again.
"The plan says implement, not architect"	The plan says what. This skill guards how. Both fire.
"The code is only in a test, the lens doesn't apply"	Test code is code. Tests accumulate the same rot. Apply the lens.