| name | system-comparison |
| description | Systematic gap assessment between two skill/tool systems. Spawns parallel research agents per domain track + one fitness agent covering 10 structural vectors (prerequisites, cost, QC, UX, skill standard, security, architecture, workspace compatibility, trigger precision, maintenance decay). Produces ranked steal-list PDF. Use when comparing LeadGrow against competitors, open-source repos, internal system variants, or evaluating whether an external skill ecosystem is worth adopting. Three modes: skill-vs-skill, skill-vs-system, external-vs-internal.
|
| version | 1.1.0 |
| maturity | validated |
| triggers | ["compare systems","gap assessment","compare against","what should we steal","system comparison","evaluate this repo","compare our skills to","gap analysis between","how does this compare to our stack","what are we missing vs","benchmark against","competitive system analysis","should we adopt this skill set","is this a skill or a system","compare two skills","which skill should we keep"] |
| feedback | {"last_reviewed":"2026-04-28T00:00:00.000Z","known_gaps":[]} |
System Comparison
Systematic gap assessment between two skill/tool systems. Spawns 3 domain agents + 1
fitness agent in parallel. Synthesizes into a ranked steal-list and moat analysis PDF.
When to Use
- Comparing LeadGrow stack against an external repo, competitor, or OSS ecosystem
- Deciding whether to adopt, fork, or ignore an external skill set
- Running periodic competitive gap analysis
- Assessing merger/integration of two internal systems
- Determining if something is a skill or should be a system/pipeline
When NOT to Use
- Pre-implementation duplicate check → use
context-gap-analysis
- General topic research → use
research skill
- Single-skill review → just read the SKILL.md directly
Output Contract
The deliverable is a PDF. Not a markdown summary, not an inline table. An editorial-quality PDF — cream/black/orange, magazine layout, cover page, SVG strength diagram, comparison blocks, steal list, moats callout — saved to temp/[system-a]-vs-[system-b]-gap-assessment.pdf.
Everything in Phases 1–3 exists to feed Phase 4. Don't call this skill done until the PDF is generated and the path is returned to the user.
Comparison Modes
Identify the mode before Phase 1. The mode determines which system paths to pass
agents and what bias to set in synthesis.
| Mode | Description | Bias Default |
|---|
| skill-vs-skill | Two skills in the workspace — decide keep/merge/deprecate | Neutral |
| skill-vs-system | Is this skill actually a system? Should it be restructured? | Architectural |
| external-vs-internal | External repo/competitor vs LeadGrow stack | Gap-finding |
Phase 1: Scope Intake (grill-me style)
Interview the user sequentially to lock scope before spawning any agents. One question at a time. Provide a recommended answer for each before asking. If the answer can be read from the workspace (skill count, file paths, tech stack), read it first — don't ask for what you can find.
Work through these questions in order. Stop when all are resolved.
Q1: What is System A?
Before asking: glob/grep the workspace to identify path, skill count, and purpose.
Recommended answer format: [name] at [path] — [N] skills, [purpose in one phrase]
Ask only if the system identity is genuinely ambiguous from context.
Q2: What is System B?
Before asking: if System B is external (URL, repo name), state what you can infer from the name. If local, read it.
Recommended answer format: same as Q1.
Q3: What comparison mode?
Recommended: external-vs-internal (most common). Offer all three:
skill-vs-skill — two workspace skills, decide keep/merge/deprecateskill-vs-system — is this skill actually a system? architectural verdict neededexternal-vs-internal — external repo/competitor vs internal stack, gap-finding
Q4: What is the comparison bias?
Recommended: neutral (neither system assumed better). Symmetrical gaps are the most useful finding.
Other options: biased toward System A, biased toward System B, specific angle (e.g., "should we migrate?").
Q5: What are the 3 domain tracks?
Recommended for outbound/GTM systems:
| Track | Covers |
|---|
| Infrastructure & List Building | Provisioning, deliverability, list sources, ICP, scoring, validation |
| Copy, QA & Send | Methodology, personalization, spam checks, upload, strategy generation |
| Measurement, Automation & Strategy | Reply intel, experiments, operational rhythm, autonomous execution |
If the domain differs, propose 3 mutually exclusive tracks that cover the full capability surface. Each track needs 4-8 dimensions. Confirm before proceeding.
Q6: What is the output filename?
Recommended: [system-a-slug]-vs-[system-b-slug]-gap-assessment.pdf in temp/.
Only ask if the user has a specific naming preference.
Once all 6 questions are resolved, state the locked scope in one block and proceed to Phase 2 without asking for confirmation.
Phase 2: Parallel Research (spawn 4 agents simultaneously)
3 domain agents + 1 fitness agent. All spawn at the same time.
Domain Agent Prompt Template (use for all 3 tracks)
Gap analysis between [System A name] and [System B name]. Your track: [TRACK NAME] only.
System A: [name] at [path]
Key skills for this track: [list specific skill folder names]
System B: [name] at [path]
Key skills for this track: [list specific skill folder names]
Read SKILL.md files from BOTH systems for each skill listed. Not directory names — actual files.
For each dimension below, output:
- What System A has (specific files + capabilities)
- What System B has (specific files + capabilities)
- WHO WINS and WHY (one sentence — commit to a verdict, no weasel words)
- GAP: What [target system] should steal (specific and actionable)
Dimensions:
1. [Dimension] — [what to compare]
2. [Dimension] — [what to compare]
3. [Dimension] — [what to compare]
4. [Dimension] — [what to compare]
Cap output at 800 words total.
Critical rules for domain agent prompts:
- Name specific skill folders — don't say "check all skills"
- 800-word hard cap — prevents synthesis context overflow
- Force "WHO WINS" verdict — no "both have strengths" outputs
- Force actionable GAP statement — not just "System B is better here"
Fitness Agent Prompt (4th agent — always the same)
Fitness assessment between [System A name] and [System B name].
System A: [name] at [path]
System B: [name] at [path]
Read the SKILL.md files, README files, and any metadata/config files available for both systems.
Rate each system on all 10 vectors below. For each vector:
- System A score: LOW / MED / HIGH + one sentence evidence
- System B score: LOW / MED / HIGH + one sentence evidence
- WHO WINS (commit to a verdict, or TIE with reason)
- What the loser should fix (specific, not generic)
VECTORS:
1. PREREQUISITES
What context, tools, APIs, or knowledge must exist before the system can run?
Assess: dependency count, dependency stability, setup complexity
2. COST IMPACT
Token burn, API calls, agent spawns, time-to-output per typical run.
Assess: how expensive is this to run daily vs monthly vs on-demand?
3. QUALITY CONTROL
Does it validate output? Forced verdicts? Review loops? Hallucination guards?
Assess: does output quality depend on the model, or does the skill enforce it?
4. USER EXPERIENCE
Friction level, interaction model (chatty vs autonomous), output format fit.
Assess: how many prompts does it take? Does it block the user or run silently?
5. SKILL STANDARD COMPLIANCE
Does it hit the canonical good-skill bar: clear triggers, scoped to one job,
SKILL.md structure, testable outputs, When NOT to Use section?
Assess: would skill-creator approve this as-is?
6. SECURITY
External API calls, key handling, prompt injection surface, data leaving workspace.
Assess: what sensitive data does it touch? Are keys hardcoded or env-sourced?
7. SYSTEM ARCHITECTURE FIT
Is the scope right for a skill? Does it need persistent state (→ system)?
Is it callable as a subroutine? Does it spawn agents internally?
Assess: skill / orchestrating-skill / pipeline / full-system — which is it really?
8. WORKSPACE COMPATIBILITY
Plugin namespace fit, routing conventions (CLAUDE.md work routing), tool hierarchy.
Assess: would it slot into this workspace without rule conflicts?
9. TRIGGER PRECISION
Are triggers unambiguous? Overlap with other skills in the workspace?
Assess: is there a risk of wrong-skill routing? Are triggers too broad or too narrow?
10. MAINTENANCE DECAY RATE
Dependencies on scraped data, external APIs, or file conventions that change often.
Assess: LOW decay (internal conventions), MED decay (stable APIs), HIGH decay (scraped/volatile)
Cap output at 600 words total.
Phase 3: Synthesis (after all 4 agents complete)
3a. Domain Matrix
From the 3 domain agents, build:
| Dimension | System A | System B | Winner |
|---|
Count wins: System A: X | System B: Y | Ties: Z
3b. Fitness Scorecard
From the fitness agent, build:
| Vector | System A | System B | Winner |
|---|
| Prerequisites | LOW/MED/HIGH | LOW/MED/HIGH | |
| Cost Impact | | | |
| Quality Control | | | |
| User Experience | | | |
| Skill Standard | | | |
| Security | | | |
| Architecture Fit | | | |
| Workspace Compatibility | | | |
| Trigger Precision | | | |
| Maintenance Decay | LOW=good | | |
Fitness wins: System A: X | System B: Y
3c. Rank Steal List
Combine domain gaps + fitness gaps. Rank by operational impact:
- What fills a gap in the daily workflow?
- What prevents a known failure mode?
- What adds a capability that doesn't exist at all?
- What improves an existing capability (lower priority)?
Each steal item must have:
- What to steal (specific skill/pattern name)
- Why it matters (one sentence)
- Effort estimate: port existing vs build new
- Which vector it addresses (domain capability or fitness vector name)
3d. Identify Moats
What does each system have that the other CAN'T easily replicate?
- Accumulated domain knowledge (client data, battle-tested patterns)
- Architectural advantages (state, audit trails, composability)
- Fitness advantages (low decay rate, high QC, clean security model)
3e. Architecture Verdict (for skill-vs-system mode)
If mode is skill-vs-system, add explicit verdict:
VERDICT: [skill | orchestrating-skill | pipeline | full-system]
REASON: [one paragraph — what triggered this classification]
RECOMMENDED RESTRUCTURE: [specific changes if verdict differs from current structure]
Phase 4: PDF Output
Generate the HTML first, then run the Puppeteer script. The PDF is the deliverable — return the file path when done.
HTML template: .claude/skills/system-comparison/template.html — full CSS + page structure with {{PLACEHOLDER}} markers. Read this template, replace placeholders with synthesized content, write to temp/, then generate PDF.
Design system: cream (#faf9f5) / black (#141413) / orange (#d97757). Fonts: Poppins (headings, labels) + Lora (body, italic). Letter size, zero browser margins, CSS padding handles whitespace.
Page Structure
- Cover — wordmark + doc-type header, large title, orange rule, subtitle, byline footer
- Executive Summary — 2-3 paragraph overview + finding callout + SVG strength diagram
- Per-track sections (one per domain track) — h2 header, per-dimension comparison blocks
- Fitness Scorecard — 10-vector table, color-coded LOW/MED/HIGH
- Full Matrix — all dimensions × 4 columns (Dimension, System A, System B, Winner)
- Steal List — numbered steps ranked by operational impact
- Moats callout — what each system has that can't be replicated
- Architecture Verdict (skill-vs-system mode only)
HTML Component Library
Every page element maps to one of these CSS classes. Build the HTML by composing these blocks.
Comparison block — one dimension, winner on top:
<div class="comparison">
<div class="comp-header winner">SYSTEM A: [VERDICT LABEL]</div>
<div class="comp-body"><p>Evidence. Specific files and capabilities.</p></div>
</div>
<div class="comparison">
<div class="comp-header loser">SYSTEM B: [VERDICT LABEL]</div>
<div class="comp-body"><p>Evidence.</p></div>
</div>
Classes: winner (orange bg, cream text), loser (light gray bg), tie (black bg, cream text).
Steal box — dark actionable gap callout:
<div class="steal-box">
<div class="steal-label">STEAL</div>
<div class="steal-body">Specific thing to port and why it matters in one sentence.</div>
</div>
Callout — orange-left-border insight box:
<div class="callout">
<div class="callout-title">THE FINDING</div>
<div class="callout-body">Summary insight. Use for executive summary and moats.</div>
</div>
Steal list step — numbered ranked item:
<div class="step">
<div class="step-num">1</div>
<div class="step-content">
<div class="step-title">What to steal</div>
<div class="step-body">Why it matters. Effort estimate. Which vector.</div>
</div>
</div>
Matrix table:
<table class="matrix">
<thead>
<tr>
<th>Dimension</th>
<th>System A</th>
<th>System B</th>
<th>Winner</th>
</tr>
</thead>
<tbody>
<tr>
<td>Dimension name</td>
<td>What A has</td>
<td class="winner-cell">What B has (winner)</td>
<td class="cb">System B</td>
</tr>
</tbody>
</table>
Winner cell classes: .lg (green tint), .cb (amber tint), .tie-cell (gray tint).
SVG strength diagram — horizontal bar chart per system showing capability coverage. Bars: green (#2d7a3a) = moat-level, orange (#d97757) = solid, light gray (#e8e6dc) = weak/missing. Wrap in .figure with <figcaption>.
Page break: <div class="pagebreak"></div> — use between major sections.
Generation Script
import puppeteer from 'puppeteer';
import { writeFileSync, readFileSync } from 'fs';
import { join } from 'path';
const htmlFile = process.argv[2] ?? join(import.meta.dir, 'comparison.html');
const outFile = process.argv[3] ?? join(import.meta.dir, 'comparison-output.pdf');
const html = readFileSync(htmlFile, 'utf-8');
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
await page.setContent(html, { waitUntil: 'networkidle0' });
const pdf = await page.pdf({
format: 'Letter',
printBackground: true,
margin: { top: '0', bottom: '0', left: '0', right: '0' },
});
writeFileSync(outFile, pdf);
await browser.close();
console.log(`PDF saved: ${outFile}`);
Run: bun temp/gen_pdf.ts temp/comparison.html temp/[output-name].pdf
Prerequisite: bun add puppeteer — already installed in temp/ in this workspace.
Validated Learnings
These are baked-in from two validated sessions (2026-04-28):
- 3 domain agents is the sweet spot. 2 = missed dimensions. 4+ = context bloat.
- 800-word cap per domain agent is critical. Without it synthesis overflows.
- Forced verdicts eliminate weasel outputs. "WHO WINS" makes comparisons actionable.
- Steal list ranked by operational impact beats ranked by complexity. "What fills a daily gap?" beats "What's easiest to port?"
- Default to neutral bias. Biased comparisons (one system assumed better) miss symmetrical gaps.
- WeasyPrint fails on Windows. Always use Puppeteer + Bun.
- SVG strength diagrams communicate faster than tables for executive summary.
- Fitness vectors need a dedicated agent. Mixing them into domain agents dilutes both streams.
Related Skills
context-gap-analysis — Pre-implementation duplicate check (narrower scope, pre-build gate)research — General workspace knowledge querypdf-guide — Editorial PDF design system (used in Phase 4)
