chekk 0.2.5 → 0.4.0

package/src/scorer.js

@@ -9,19 +9,14 @@
 // ── Tier thresholds (match GitHub analysis) ──
 
 const TIERS = [
-  { name: 'LEGENDARY',  min: 85, badge: '🌟🌟🌟', percentile: 'Top 1%' },
-  { name: 'ULTRA RARE', min: 73, badge: '🌟🌟',   percentile: 'Top 5%' },
-  { name: 'RARE',       min: 60, badge: '⭐',      percentile: 'Top 15%' },
-  { name: 'UNCOMMON',   min: 47, badge: '◆',       percentile: 'Top 30%' },
-  { name: 'COMMON',     min: 0,  badge: '●',       percentile: 'Top 50%' },
+  { name: 'LEGENDARY',  min: 85, badge: '\uD83C\uDF1F\uD83C\uDF1F\uD83C\uDF1F', percentile: 'Top 1%' },
+  { name: 'ULTRA RARE', min: 73, badge: '\uD83C\uDF1F\uD83C\uDF1F',   percentile: 'Top 5%' },
+  { name: 'RARE',       min: 60, badge: '\u2B50',      percentile: 'Top 15%' },
+  { name: 'UNCOMMON',   min: 47, badge: '\u25C6',       percentile: 'Top 30%' },
+  { name: 'COMMON',     min: 0,  badge: '\u25CF',       percentile: 'Top 50%' },
 ];
 
 // ── Archetype definitions ──
-// Each archetype has a match function based on the 4 CLI dimension scores:
-//   decomposition (thinking), debugCycles (debugging),
-//   aiLeverage (AI leverage), sessionStructure (workflow)
-//
-// Tier-restricted: archetypes only match within their allowed tier range.
 
 const ARCHETYPES = [
   // ── LEGENDARY (85+) ──
@@ -29,8 +24,11 @@ const ARCHETYPES = [
     id: 'THE_10X_ENGINEER',
     name: 'THE 10X ENGINEER',
     tierRange: ['LEGENDARY'],
-    match: (s) => true, // If you hit LEGENDARY, you're a 10x
+    match: (s) => true,
     priority: 1,
+    distribution: '< 1%',
+    description: 'Engineers classified as 10x demonstrate exceptional capability across all dimensions. They decompose complex systems methodically, debug with surgical precision, leverage AI as a strategic partner, and maintain disciplined workflows. This classification indicates mastery-level AI-augmented engineering.',
+    bestFor: 'CTO, founding engineer, or principal engineer roles requiring full-stack autonomy.',
   },
 
   // ── ULTRA RARE (73-84) ──
@@ -38,17 +36,21 @@ const ARCHETYPES = [
     id: 'THE_ARCHITECT',
     name: 'THE ARCHITECT',
     tierRange: ['ULTRA RARE'],
-    // High decomposition + structured workflow + strong leverage
     match: (s) => s.decomposition >= 70 && s.sessionStructure >= 65,
     priority: 2,
+    distribution: '3%',
+    description: 'Architects demonstrate exceptional problem decomposition paired with disciplined session structure. They think in systems, set context deliberately, and use AI for design-level decisions rather than line-level coding. Their sessions show a plan-first, build-second pattern.',
+    bestFor: 'Staff engineer, technical lead, or systems architect roles.',
   },
   {
     id: 'THE_PROFESSOR',
     name: 'THE PROFESSOR',
     tierRange: ['ULTRA RARE'],
-    // Exceptional at explaining: high decomposition, detailed prompts, strong context-setting
     match: (s) => s.decomposition >= 65 && s.sessionStructure >= 70,
     priority: 3,
+    distribution: '2%',
+    description: 'Professors combine deep analytical thinking with structured, pedagogical workflows. Their prompts read like detailed specifications. They set context meticulously and review output critically, treating AI as a collaborator that needs clear direction.',
+    bestFor: 'Technical leadership, developer education, or architecture review roles.',
   },
 
   // ── RARE (60-72) ──
@@ -56,25 +58,31 @@ const ARCHETYPES = [
     id: 'THE_SPECIALIST',
     name: 'THE SPECIALIST',
     tierRange: ['RARE'],
-    // Deep focused work: high debug efficiency + high leverage in specific domain
     match: (s) => s.debugCycles >= 70 && s.aiLeverage >= 65,
     priority: 4,
+    distribution: '6%',
+    description: 'Specialists demonstrate deep expertise in targeted domains with precise, efficient debugging patterns and strategic AI tool usage. They favor depth over breadth and tend toward long, focused sessions on complex problems.',
+    bestFor: 'Senior engineer roles requiring deep domain expertise and autonomous execution.',
   },
   {
     id: 'THE_SYSTEMS_THINKER',
     name: 'THE SYSTEMS THINKER',
     tierRange: ['RARE'],
-    // Strong decomposition + structured approach to complex problems
     match: (s) => s.decomposition >= 65 && s.sessionStructure >= 60,
     priority: 5,
+    distribution: '5%',
+    description: 'Systems Thinkers break complex problems into well-structured components with deliberate context-setting. Their prompt patterns show they understand how parts connect to wholes, making them effective at designing and maintaining large systems.',
+    bestFor: 'Platform engineering, infrastructure, or technical architecture roles.',
   },
   {
     id: 'THE_MAINTAINER',
     name: 'THE MAINTAINER',
     tierRange: ['RARE'],
-    // Reliable workflow + solid debugging: keeps things running
     match: (s) => s.sessionStructure >= 60 && s.debugCycles >= 60,
     priority: 6,
+    distribution: '4%',
+    description: 'Maintainers combine reliable workflow discipline with solid debugging efficiency. They review before shipping, set context for each task, and resolve issues methodically. Their consistency makes them the backbone of production systems.',
+    bestFor: 'Senior engineer or tech lead roles where reliability and code quality are paramount.',
   },
 
   // ── UNCOMMON (47-59) ──
@@ -82,44 +90,54 @@ const ARCHETYPES = [
     id: 'THE_CRAFTSPERSON',
     name: 'THE CRAFTSPERSON',
     tierRange: ['UNCOMMON'],
-    // Quality obsession: high debug precision + structured sessions
     match: (s) => s.debugCycles >= 60 && s.sessionStructure >= 55,
     priority: 7,
+    distribution: '8%',
+    description: 'Craftspeople show attention to quality through precise debugging and structured sessions. They may not yet operate at the architectural level, but their care for correctness and process indicates strong engineering foundations.',
+    bestFor: 'Mid-to-senior engineer roles focused on quality and reliability.',
   },
   {
     id: 'THE_BUILDER',
     name: 'THE BUILDER',
     tierRange: ['UNCOMMON'],
-    // Well-rounded: decent across all dimensions
     match: (s) => {
       const min = Math.min(s.decomposition, s.debugCycles, s.aiLeverage, s.sessionStructure);
       return min >= 45;
     },
     priority: 8,
+    distribution: '10%',
+    description: 'Builders are well-rounded engineers with competence across all dimensions. No major weaknesses, no extreme spikes. They get things done consistently and adapt to different types of problems without over-specializing.',
+    bestFor: 'Full-stack or generalist engineer roles requiring versatility.',
   },
   {
     id: 'THE_CONTRIBUTOR',
     name: 'THE CONTRIBUTOR',
     tierRange: ['UNCOMMON'],
-    // Strong AI leverage + decent decomposition: collaborates well with AI
     match: (s) => s.aiLeverage >= 55 && s.decomposition >= 50,
     priority: 9,
+    distribution: '7%',
+    description: 'Contributors show strong AI collaboration skills with good problem decomposition. They leverage AI effectively as a coding partner and break work into manageable pieces, though workflow discipline and debugging precision have room to grow.',
+    bestFor: 'Engineer roles in AI-forward teams with collaborative development practices.',
   },
   {
     id: 'THE_HIDDEN_GEM',
     name: 'THE HIDDEN GEM',
     tierRange: ['UNCOMMON'],
-    // Strong skills but unstructured: high debug or leverage but low structure
     match: (s) => (s.debugCycles >= 55 || s.aiLeverage >= 55) && s.sessionStructure < 50,
     priority: 10,
+    distribution: '6%',
+    description: 'Hidden Gems demonstrate strong technical skills in debugging or AI leverage but lack workflow structure. They likely produce good output in bursts but could dramatically improve by adding session discipline. High ceiling, underdeveloped process.',
+    bestFor: 'Fast-moving startup roles where output matters more than process.',
   },
   {
     id: 'THE_EXPLORER',
     name: 'THE EXPLORER',
     tierRange: ['UNCOMMON'],
-    // High leverage + curiosity-driven: research-heavy prompting
     match: (s) => s.aiLeverage >= 50,
     priority: 11,
+    distribution: '9%',
+    description: 'Explorers are curiosity-driven engineers who use AI heavily for research, investigation, and learning. Their exploratory prompting shows intellectual breadth, though they may benefit from more structured approaches to execution.',
+    bestFor: 'R&D, prototyping, or innovation-focused engineer roles.',
   },
 
   // ── COMMON (0-46) ──
@@ -127,33 +145,41 @@ const ARCHETYPES = [
     id: 'THE_TINKERER',
     name: 'THE TINKERER',
     tierRange: ['COMMON'],
-    // Practical problem-solving: decent debug + some leverage
     match: (s) => s.debugCycles >= 40 && s.aiLeverage >= 35,
     priority: 12,
+    distribution: '12%',
+    description: 'Tinkerers show practical problem-solving instincts with emerging AI skills. They debug adequately and are beginning to use AI beyond basic code generation, but all dimensions have significant room for growth.',
+    bestFor: 'Junior-to-mid engineer roles with growth opportunities.',
   },
   {
     id: 'THE_GRINDER',
     name: 'THE GRINDER',
     tierRange: ['COMMON'],
-    // High volume, iterative: lots of exchanges, keeps going
     match: (s) => s.decomposition >= 35,
     priority: 13,
+    distribution: '11%',
+    description: 'Grinders are high-volume, iterative engineers. They keep going through problems with persistence. The volume of work is there but the approach could benefit from more strategic thinking and structured workflows.',
+    bestFor: 'Environments where persistence and volume are valued.',
   },
   {
     id: 'THE_HOBBYIST',
     name: 'THE HOBBYIST',
     tierRange: ['COMMON'],
-    // Active but early: some leverage or debugging skill
     match: (s) => s.aiLeverage >= 30 || s.debugCycles >= 30,
     priority: 14,
+    distribution: '10%',
+    description: 'Hobbyists are active but early in their AI-augmented engineering journey. They show some skill in debugging or AI usage but haven\'t yet developed consistent patterns across dimensions.',
+    bestFor: 'Early-career roles with mentorship and structured onboarding.',
   },
   {
     id: 'THE_APPRENTICE',
     name: 'THE APPRENTICE',
     tierRange: ['COMMON'],
-    // Default fallback for COMMON tier
     match: () => true,
     priority: 99,
+    distribution: '7%',
+    description: 'Apprentices are at the beginning of their AI-augmented engineering practice. Their prompt patterns suggest they\'re still learning how to effectively collaborate with AI tools. Significant growth potential across all dimensions.',
+    bestFor: 'Entry-level roles with training programs and mentorship.',
   },
 ];
 
@@ -183,7 +209,7 @@ export function computeOverallScore(metrics) {
 
   const archetype = tierArchetypes.find(a => a.match(scores))
     || tierArchetypes[tierArchetypes.length - 1]
-    || { id: 'THE_APPRENTICE', name: 'THE APPRENTICE' };
+    || ARCHETYPES[ARCHETYPES.length - 1];
 
   return {
     overall,
@@ -191,6 +217,9 @@ export function computeOverallScore(metrics) {
     archetype: {
       id: archetype.id,
       name: archetype.name,
+      description: archetype.description,
+      distribution: archetype.distribution,
+      bestFor: archetype.bestFor,
     },
     tier: tier.name,
     tierBadge: tier.badge,