Skip to content

w5h1.md

Latest commit

 

History

History
56 lines (42 loc) · 1.96 KB

w5h1.md

File metadata and controls

56 lines (42 loc) · 1.96 KB

W5H1 — Completeness Scan

W5H1 runs after the 9 lenses. While lenses find issues with what exists, W5H1 finds what's missing.

The Questions

Question What It Finds Overlap with Lenses
Why Missing rationale, unexplained design choices Unique — no lens asks "why does this exist?"
What Unclear behavior Covered by 🏷️ Name
How Unclear mechanism Covered by ✂️ Simplify
Where Wrong location Covered by 🧱 Boundary
Who Missing ownership, unclear responsibility Unique — no lens asks "who maintains this?"
When Missing expiry, timeouts, edge case timing Unique — no lens asks "when does this expire?"

Unique Value

The overlap with lenses is intentional — W5H1 is a completeness check, not a replacement. Its unique value is in three questions:

Why — Missing Rationale

Non-obvious choices need comments. Future maintainers will ask "why is this timeout 35 seconds?" or "why does this fallback to an alternative field name?" If the answer isn't in the code, it will be lost.

Finding: Write timeout is 35s with no explanation.
Fix: Add comment — "Higher than read: accounts for upstream vendor latency."

Who — Missing Ownership

Code without an owner decays silently. Who gets paged when this breaks? Who reviews changes to this module? For projects above a certain scale, a CODEOWNERS file or equivalent is essential.

When — Missing Expiry

Things that should expire but don't:

  • Session tokens without MaxAge
  • Cache entries without TTL
  • Feature flags without removal dates
  • API keys without rotation schedules

Evidence Format

### W5H1 Completeness Scan
| Q | Finding | File:Line |
|---|---------|-----------|
| Why | No comment explaining 35s write timeout | cmd/main.py:59 |
| When | Session cookie has no MaxAge | middleware.ts:20 |
| Who | No CODEOWNERS file | (project root) |