---

name: antipattern-catalog description: Document technical debt, anti-patterns, and patterns to avoid from analyzed frameworks. Use when (1) creating a "Do Not Repeat" list from framework analysis, (2) categorizing observed code smells and issues, (3) assessing severity of architectural problems, (4) generating remediation suggestions, or (5) synthesizing lessons learned across multiple frameworks.

Anti-Pattern Catalog

Documents technical debt and patterns to avoid.

Process

1. Collect observations — Gather issues from Phase 1 & 2 analyses
2. Categorize — Structural, behavioral, observability, performance
3. Assess severity — Critical, major, minor, cosmetic
4. Generate remediation — Suggest fixes for each pattern
5. Create checklist — "Do Not Repeat" guidelines

Anti-Pattern Categories

Structural Anti-Patterns

Issues with code organization, inheritance, and modularity.

Behavioral Anti-Patterns

Issues with runtime behavior and logic.

Observability Anti-Patterns

Issues with debugging and monitoring.

Performance Anti-Patterns

Issues affecting speed and resource usage.

Severity Assessment

Critical (P0)

• Security vulnerabilities
• Data loss risk
• Infinite loops without guards
• Production outage risk

Major (P1)

• Performance issues >2x slowdown
• Poor error handling
• Difficult to extend
• Concurrency bugs

Minor (P2)

• Code style issues
• Minor inefficiencies
• Documentation gaps
• Inconsistent patterns

Cosmetic (P3)

• Naming conventions
• Formatting
• Minor redundancy

Catalog Entry Template

Copy### [Pattern Name]

**Category**: [Structural/Behavioral/Observability/Performance]
**Severity**: [Critical/Major/Minor/Cosmetic]
**Framework(s)**: [Where observed]

#### Description
[Brief explanation of the anti-pattern]

#### Example
[Code snippet showing the problem]

#### Impact
- [Impact 1]
- [Impact 2]

#### Remediation
[How to fix or avoid this pattern]

#### Code Example (Fixed)
[Corrected code snippet]

Common Anti-Patterns Deep Dive

Deep Inheritance Hell

Problem:

Copyclass Agent(BaseAgent):
    pass

class BaseAgent(RunnableAgent):
    pass

class RunnableAgent(ExecutableAgent):
    pass

class ExecutableAgent(ConfigurableAgent):
    pass

class ConfigurableAgent(LoggableAgent):
    pass

class LoggableAgent(ABC):
    pass

# 6 layers! Which method comes from where?

Remediation: Prefer composition over inheritance

Copyclass Agent:
    def __init__(
        self,
        executor: Executor,
        config: Config,
        logger: Logger
    ):
        self.executor = executor
        self.config = config
        self.logger = logger

Silent Tool Failures

Problem:

Copydef run_tool(self, tool, args):
    try:
        return tool.execute(args)
    except Exception:
        return None  # Error lost forever!

Remediation: Capture and propagate errors

Copydef run_tool(self, tool, args) -> ToolResult:
    try:
        output = tool.execute(args)
        return ToolResult(success=True, output=output)
    except Exception as e:
        return ToolResult(
            success=False,
            error=f"{type(e).__name__}: {e}",
            traceback=traceback.format_exc()
        )

Hidden LLM Response

Problem:

Copyclass LLMWrapper:
    def generate(self, prompt: str) -> str:
        response = self.client.chat(prompt)
        return response.content  # Token counts, model info lost!

Remediation: Expose full response

Copyclass LLMWrapper:
    def generate(self, prompt: str) -> LLMResponse:
        response = self.client.chat(prompt)
        return LLMResponse(
            content=response.content,
            model=response.model,
            usage=TokenUsage(
                prompt=response.usage.prompt_tokens,
                completion=response.usage.completion_tokens
            ),
            raw=response  # Always keep raw
        )

Output Template

Copy# Anti-Pattern Catalog: [Analysis Name]

## Summary

| Severity | Count |
|----------|-------|
| Critical | 2 |
| Major | 5 |
| Minor | 8 |
| Cosmetic | 3 |

## Critical Issues

### 1. [Pattern Name]
[Full catalog entry]

### 2. [Pattern Name]
[Full catalog entry]

## Major Issues

### 1. [Pattern Name]
[Full catalog entry]

...

## Do Not Repeat Checklist

- [ ] Never use more than 3 levels of inheritance
- [ ] Always expose raw LLM response with token counts
- [ ] Never swallow exceptions without logging
- [ ] Always include step limits on agent loops
- [ ] Never mutate shared state without locks
- [ ] Always provide structured error feedback to LLM
...

Integration

• Inputs from: All Phase 1 & 2 analysis skills
• Feeds into: architecture-synthesis for design decisions
• Related: comparative-matrix for pattern comparison