feat(auditor): implement upskill/auditor — cross-skill session analyzer [v1.1+]

[ngouy]

upskill/auditor — Implementation Brief

Deferred to v1.1+. v1 focuses on publisher (#2) and doctor (#3).

What This Is

auditor answers one question: "How are my loaded skills interacting with each other and affecting my session right now?"

It does not analyze individual skill quality (that's doctor's job). It analyzes the relationships between loaded skills — conflicts, overlaps, token budget distribution, and overall session health.

Reference: VISION.md → Section "upskill/auditor"
Session structure: brainstorm → plan → implement → review (do not skip or combine)

---

How It Differs From doctor

This is the most important distinction:

	doctor	auditor
Scope	One skill at a time	All loaded skills together
Question	"Is this skill well-written and safe?"	"How do my loaded skills interact with each other?"
Finds	Quality issues, bad patterns, security risks in a single skill	Conflicts between skills, overlapping triggers, token bloat
Output	Per-skill findings with fixes	Session-level snapshot with cross-skill analysis

They are complementary: auditor might say "my-workflow and commit-helper have overlapping triggers" — then you'd run doctor on each individually to decide which to narrow.

---

Scope Boundary

Auditor analyzes:

• All loaded skills and how they relate to each other
• Token footprint of each skill and total session cost
• Cross-skill conflicts (skill A says X, skill B says Y)
• Skill vs. CLAUDE.md conflicts
• Trigger overlap (two skills firing on the same context)

Auditor does NOT analyze:

• Individual skill quality (no structural checks, no missing-element checks — that's doctor)
• Per-skill security patterns (no Guardian-mode checks — that's doctor)
• The content of your conversation
• Your codebase or project files

---

The Three-Section Report

Section 1: Token Inventory

LOADED SKILLS
─────────────────────────────────────────────────────────────────────
Skill                    Source    Tokens (est.)    % of total
─────────────────────────────────────────────────────────────────────
manager                  plugin    ~180             8%
publisher                plugin    ~240             11%
doctor                   plugin    ~520             23%
auditor                  plugin    ~310             14%
commit                   plugin    ~150             7%
my-custom-workflow       local     ~840             37%
─────────────────────────────────────────────────────────────────────
TOTAL                              ~2,240

[!] my-custom-workflow is consuming 37% of the skill token budget.
    Consider reviewing it with doctor.

Token estimation: character count ÷ 4, rounded. Always labeled as (est.).

Section 2: Cross-Skill Analysis

Auditor's unique contribution — analysis that no single-skill tool can provide.

CROSS-SKILL ANALYSIS
─────────────────────────────────────────────────────────────────────
[CONFLICT] my-custom-workflow ↔ CLAUDE.md
           CLAUDE.md says "always use TypeScript".
           my-custom-workflow says "use JavaScript for scripts".
           This creates ambiguous behavior when writing scripts.

[OVERLAP]  my-custom-workflow ↔ commit
           Both trigger on "when I am working on code changes".
           These skills may compete for the same context.
           Recommendation: Narrow one or both triggers.

[OK]       No circular references detected.
[OK]       No other cross-skill conflicts found.
─────────────────────────────────────────────────────────────────────
1 conflict, 1 overlap

Cross-skill check categories:

• Skill vs. CLAUDE.md instruction conflicts (with specific text quoted)
• Skill vs. skill instruction conflicts
• Trigger overlap (near-identical activation conditions)
• Circular references (skill A loads skill B which loads skill A)

Section 3: Session Health Summary

SESSION HEALTH SUMMARY
─────────────────────────────────────────────────────────────────────
Overall rating: NEEDS ATTENTION

What's healthy:
  - 5 of 6 skills have reasonable token footprints
  - No circular references detected

What needs attention:
  - [CONFLICT] my-custom-workflow conflicts with CLAUDE.md
  - [OVERLAP]  my-custom-workflow and commit have overlapping triggers
  - [WARN]     my-custom-workflow consumes 37% of the skill token budget

Recommended actions (priority order):
  1. Run doctor my-custom-workflow to resolve the CLAUDE.md conflict.
  2. Narrow the trigger on my-custom-workflow or commit to eliminate overlap.
─────────────────────────────────────────────────────────────────────

Overall ratings:

• HEALTHY — no conflicts, no overlaps, token distribution reasonable
• NEEDS ATTENTION — conflicts or overlaps detected, or one skill dominates token budget
• CRITICAL — CLAUDE.md conflict detected

---

What auditor Must Never Do

• Never perform per-skill quality analysis (use doctor)
• Never perform per-skill security analysis (use doctor)
• Never read or reference conversation content
• Never analyze the user's code, commits, or project state
• Never modify any skill files
• Never claim certainty about token counts — always label as estimates
• Never duplicate doctor's work — recommend running doctor when per-skill analysis is needed

---

When to Use (trigger signals for SKILL.md description)

• User wants to understand what skills are loaded and their token cost
• User suspects loaded skills are conflicting with each other or with CLAUDE.md
• User notices overlapping behavior between skills
• User wants a session-level health check for their skill setup
• User asks for a session audit, skill snapshot, or "what's loaded right now"

---

Quality Gate

Before this skill is considered done:

• Passes doctor --curator on itself with zero CRITICAL or HIGH findings
• All three report sections present in default output
• Cross-skill analysis covers all 4 categories (CLAUDE.md conflicts, skill conflicts, trigger overlap, circular refs)
• Token estimates always labeled as approximate
• Scope boundary enforced — no per-skill quality or security checks
• Recommendations always point to doctor for per-skill issues
• Token footprint target: ~400 tokens (verify with character count)

[ngouy]

Review update — deferred to v1.1+, scope refocused

Following a critical design review (#5), auditor has been deferred to v1.1+ and its scope has been significantly refocused.

Core change: auditor is now the cross-skill analyzer

The original spec had auditor duplicating much of doctor's work (malicious pattern checks, structural quality checks, missing elements). The new scope is exclusively cross-skill analysis — things no single-skill tool can catch:

1. Token inventory — what's loaded, what it costs, who's dominating the budget
2. Cross-skill conflicts — skill A says X, skill B says Y (with specific text quoted)
3. Skill vs. CLAUDE.md conflicts — loaded skills contradicting project instructions
4. Trigger overlap — two skills with near-identical activation conditions
5. Circular references — skill A loads skill B which loads skill A

What was removed (now exclusively doctor's job):

• Per-skill malicious pattern checks
• Per-skill structural quality checks
• Per-skill missing element checks
• Transparency suppression checks (per-skill)

Report structure changed:

• Old: 4 sections (inventory, hard checks, soft checks, summary)
• New: 3 sections (token inventory, cross-skill analysis, session health summary)

Overall ratings simplified:

• HEALTHY — no conflicts, no overlaps, reasonable token distribution
• NEEDS ATTENTION — conflicts or overlaps detected
• CRITICAL — CLAUDE.md conflict detected