# 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." |