Critical Analysis Patterns

Critical Analysis Patterns

Beyond technical validation, analyze alignment between intent and implementation.

Canonical Implementation Principle 📐

skillmaker aims for "canonical implementation" of plugins, agents, and marketplaces.

Active Recommendation

When analyzing projects, actively recommend skillmaker's "good practices" for similar/equivalent features:

When Project Uses Different Approach

If the project uses a different method, determine:

Evaluation Criteria

## Deficiency Indicators (recommend change)
- Reinventing what skillmaker already solved
- Missing enforcement (MUST keywords without hooks)
- Ignoring known anti-patterns
- Unnecessary complexity vs canonical approach

## Domain-Specific Indicators (respect choice)
- Different constraints that invalidate canonical approach
- Performance requirements that justify deviation
- Ecosystem compatibility requirements
- Documented rationale for deviation

Example: MCP Analysis

When project uses MCP:

1. Load: Skill("skillmaker:mcp-gateway-patterns")
2. Check: Is Daemon SSE pattern being used?
3. If not:
   • Is there a documented reason?
   • Does their approach handle subagent isolation?
   • Recommend Daemon pattern if deficient

Core Questions (6 Questions)

Ask these questions for every component:

1. Existence Justification

- "Why is this here?"
- "What breaks if we remove it?"
- "Can it be replaced with something else?"

2. Intent-Implementation Alignment

- "Does the name reflect the actual role?"
- "Does declared purpose match actual behavior?"
- "Are documentation and code synchronized?"

3. Consistency

- "Are similar things being handled differently?"
- "Are patterns A and B mixed?"
- "Is exceptional handling justified?"

4. Unused Capabilities

- "Is there something declared but not used?"
- "Is there something implemented but never called?"
- "Why isn't it being used?"

5. Complexity Justification

- "Is this complexity truly necessary?"
- "Is there a simpler alternative?"
- "Is this over-engineering?"

6. Fundamental Redesign 🔥

"Idiots, this solves everything - why can't you see it?"

Beyond conservative solutions (deletion, exceptions, workarounds), ask questions that eliminate constraints themselves:

- "If this problem keeps recurring, isn't the system itself wrong?"
- "Are we taking this constraint/limitation for granted?"
- "Is there a completely different approach?"
- "If there's a 10x better method, what is it?"
- "If we rebuilt this from scratch, how would we do it?"

When to apply:

• Same type of problem found 3+ times
• Conservative solution feels like a "band-aid"
• Feeling of "why is this so complicated?"

Analysis Process

Step 1: Component Inventory

# Collect all components
agents/*.md, skills/*/SKILL.md, commands/*.md, hooks/hooks.json

Step 2: Relationship Mapping

Step 3: Apply Core Questions

Apply 6 questions to each component and discover inconsistencies

Step 4: Organize Findings

Output Format

### Philosophical Analysis Results

| Finding | Question | Suggestion |
|---------|----------|------------|
| {what} | {why?} | {alternative} |

Red Flags (Signals That Require Immediate Questioning)

Solution Synthesis

Diagnosis + Prescription = Consulting

When problems are found, provide solutions at two levels:

Level 1: Conservative Solutions

Solutions found within existing patterns/skills:

Level 2: Radical Solutions 🔥

"If you're confident, propose it even if it's not in existing patterns"

When conservative solutions feel like band-aids, consider:

Criteria for proposing radical solutions:

1. First explain limits of conservative solution
2. Explicitly state trade-offs of radical solution
3. Indicate confidence level (High/Medium/Exploratory)
4. Provide concrete execution steps

Output format:

### 🔥 Radical Solution: {proposal}

**Why this is right**:
{rationale - fundamental limits of existing approach}

**Trade-off**:
- Gains: {benefits}
- Losses: {costs}

**Confidence Level**: High | Medium | Exploratory

**Execution Steps**:
1. {step 1}
2. {step 2}
...

Detailed process: Read("references/solution-synthesis.md")

Quick Checklist

Items to verify quickly during analysis:

• Do all agents/ actually function as agents?
• Do skill declarations match Skill() usage?
• Can similar Hooks be extracted into common patterns?
• Are there old architecture remnants in documentation?
• Can each component's existence be explained in one sentence?
• Does the project follow skillmaker's canonical patterns?
• If different approach used, is there documented rationale?