80 lines
4.5 KiB
Markdown
80 lines
4.5 KiB
Markdown
# Essence Detection Signals
|
||
|
||
How to identify the standout design in a project when the user doesn't specify a direction.
|
||
|
||
## Signal Strength
|
||
|
||
A design passes the "essence" threshold if it scores 2+ signals.
|
||
|
||
### Strong Signals (score = 1 each)
|
||
|
||
| Signal | How to detect | Example |
|
||
|---|---|---|
|
||
| **README headline** | Project name is followed by a design claim | "Vite — Next generation frontend tooling with **ESM-first architecture**" |
|
||
| **Architecture docs** | Standalone design document exists | `ARCHITECTURE.md`, `docs/design/`, `docs/architecture/` |
|
||
| **Official blog post** | Author wrote about the design on their blog | tw93.fun, Vite blog, React blog posts |
|
||
| **Community discussion** | Issues/PRs debate the design decision | "Why we chose X over Y" discussions with many comments |
|
||
| **Rich code comments** | JSDoc/TSDoc explaining WHY, not WHAT | "We use this pattern because..." with detailed reasoning |
|
||
|
||
### Objective Signals (score = 1 each, no subjective judgment needed)
|
||
|
||
| Signal | How to detect | Example |
|
||
|---|---|---|
|
||
| **Cross-module contract** | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. | `Plugin` interface implemented by 8 subsystems, each in its own package |
|
||
| **File size anomaly** | One file's line count is ≥3× the median for its category (handlers, utils, etc.) | Average handler: 50 lines. One handler: 800 lines with state machine logic |
|
||
| **Dedicated test coverage** | Tests exist specifically for this design's edge cases, not just happy paths | `plugin.test.ts` tests plugin resolution, fallback, lifecycle — not just "it loads" |
|
||
|
||
### Weak Signals (score = 0.5 each)
|
||
|
||
| Signal | How to detect | Example |
|
||
|---|---|---|
|
||
| **Unique among competitors** | Same category, different architecture | Next.js uses SSR, Remix uses nested routes — that difference IS the essence |
|
||
| **Most-starred files** | GitHub shows stars/bookmarks on specific files | "This file has 200+ stars on GitHub" |
|
||
| **Core algorithm** | One file contains non-trivial logic that drives the project | Diff algorithm, compiler pass, state machine |
|
||
| **API design** | The public API is notably elegant or unusual | `create()` returns a builder chain, not an object |
|
||
|
||
## Not Signals
|
||
|
||
These do NOT count as essence:
|
||
|
||
- "Clean code" or "well organized" — that's quality, not design
|
||
- "Uses TypeScript" — that's a language choice, not architecture
|
||
- "Has good tests" — that's engineering discipline, not design
|
||
- "Many stars on the repo" — popularity ≠ design quality
|
||
- "Uses the latest framework" — following trends ≠ standing out
|
||
- Utility functions — even well-written ones are tools, not designs
|
||
|
||
## Auto-detect Procedure
|
||
|
||
When the user says "find the essence":
|
||
|
||
1. **Read README fully.** What is the #1 feature the author leads with? That's a candidate.
|
||
2. **Check for design docs.** Is there `ARCHITECTURE.md` or equivalent? That's a candidate.
|
||
3. **Scan the import graph.** Which file is imported by the most other files? Use `grep -r "import.*from" src/ | sort | uniq -c | sort -rn` or equivalent. The top result is likely the core.
|
||
4. **Check file sizes.** Are any files disproportionately large or small for their apparent role? That signals hidden complexity.
|
||
5. **Check uniqueness.** Compare with 1-2 well-known alternatives. What does this project do differently?
|
||
6. **Present 1-2 candidates** to the user with evidence. Let them choose or auto-select the strongest.
|
||
|
||
### Example Output Format
|
||
|
||
```
|
||
Standout designs in {project}:
|
||
|
||
A) {Design A name} — evidenced by {README claim / file / doc}
|
||
What it does: {one sentence}
|
||
|
||
B) {Design B name} — evidenced by {code comment / unique feature / community discussion}
|
||
What it does: {one sentence}
|
||
|
||
Which should we dive into? (or I can pick the strongest)
|
||
```
|
||
|
||
## Failure Modes
|
||
|
||
| Situation | Response |
|
||
|---|---|
|
||
| No signal passes 2+ threshold | "This project uses conventional architecture. Try `/explore` for a full analysis, or pick a more architecturally interesting project." |
|
||
| User-specified module doesn't exist | Stop. Do NOT suggest an alternative. Tell the user the path doesn't exist. |
|
||
| Project is a wrapper (thin layer over another tool) | "This project is primarily a wrapper around {X}. The design is in {X}, not here. Try analyzing {X} instead." |
|
||
| Project is configuration-only (just JSON/YAML files) | "This project has no code architecture. It's configuration-driven. Try `/explore` for a full overview instead." |
|