git-learn/skills/essence/references/essence-signals.md

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