prevent-command-bloat

Previne Slash Commands inchados - separação de responsabilidades, tell don't teach, escopo focado

Prevent Command Bloat

Esta SKILL previne criação de Slash Commands inchados e excessivos, aplicando princípios de separação de responsabilidades, "tell don't teach", simplificação de SubAgents e escopo focado.

Shared Base

This file contains the principles and policies shared by all prevention SKILLs (prevent-skill-bloat, prevent-agent-bloat, prevent-command-bloat, prevent-file-floods).

Objective

Prevent behaviors that frustrate users:

  1. Creating much more than requested (extra files, unnecessary validations, unsolicited examples)
  2. Exaggerated and over-written descriptions (excessive verbosity when brevity would be better)
  3. Returning to the same problems after refactoring (not learning from user corrections)
  4. Implementations with parts from various iterations (inconsistent final code/definition)

File Creation Policy

NEVER create automatically:

  • Documentation (README.md, ANALYSIS.md, REPORT.md, SUMMARY.md, etc.)
  • Explanations, analyses, or reviews in files
  • Responses to "explain", "analyze", "what is", "how does"

ALWAYS create:

  • Functional code (.py, .js, .ts, etc.) when implementing features
  • Essential configuration (package.json, requirements.txt, .env.example)
  • Explicitly requested files ("create a file", "save to")

ASK before:

  • Ambiguous request
  • File >100 lines (better in file than chat)
  • Multi-file projects with unclear structure

Behavior Mode: Contextual Analysis

Apply contextual analysis - there is no rigid template:

Simple and direct → Minimal implementation

  • DO: Create only what was requested
  • DO NOT: Add long descriptions, redundancies, extra explanations

Complex with composition → Create necessary files

  • DO: Use sub-skill composition when it increases efficiency
  • DO: Structure complex resources adequately

Deterministic → Implement exactly what was requested

  • DO: Implement what was asked (not "what could be")
  • DO NOT: Add multiple possibilities to deterministic cases

Ambiguous → Ask instead of guessing

  • DO: Use AskUserQuestion when unclear
  • DO NOT: Implement as precaution or "just in case"

Assertive Execution

BEFORE creating or modifying any resource:

  1. IDENTIFY: What is this resource's single responsibility?

    • Must have ONE clear and specific responsibility
    • Name should reflect the responsibility

  2. IMPLEMENT: Only what was explicitly requested

    • DO: Implement exactly what was asked
    • DO NOT: Add "possibilities" or "variations"
    • DO NOT: Create extra resources "as precaution"

  3. WRITE: Imperative mode, direct instructions

    • MUST: Imperative language ("DO this", "MUST do")
    • DO NOT: Ambiguous language ("could", "maybe", "consider")

  4. VERIFY: Is response deterministic for given input?

    • Same input should generate same output
    • Predictable and consistent behavior

IF unsure about user intent: → USE: AskUserQuestion tool to clarify → DO NOT: Implement multiple variations or guess

IF detect principle violation DURING work: → STOP immediately → WARN: "⚠️ [action] may violate [principle X] in principles/[file].md" → WAIT: For user confirmation before proceeding

Princípios Específicos para Slash Commands

Principles for Slash Commands

Principle I: Single Responsibility

MUST: A command executes one specific and well-defined task MUST: Command name clearly reflects the task (e.g.: /analyze-deps, /fix-lint, /review-security) DO NOT: Create commands with multiple unrelated responsibilities DO NOT: Generic commands like /helper, /util, /process

Principle II: Imperative Structure

MUST: Instructions written in direct imperative mode

  • "Analyze dependencies and report vulnerabilities"
  • "Fix linting errors in specified files"
  • "Review code for security issues"

DO NOT: Use ambiguous or conditional language

  • ❌ "You could analyze..."
  • ❌ "Maybe check..."
  • ❌ "Considers analyzing..."

MUST: Deterministic actions for known inputs MUST: Define all expected behavior variations

Principle III: Deterministic Code

MUST: Same input → Same output (predictable behavior) MUST: All execution conditions must be explicit MUST: Behavior variations depend only on provided input

DO NOT: Leave behavior undefined or based on "trial" DO NOT: Generate multiple alternatives without clear selection criteria DO NOT: Behavior that varies between executions for same input

Principle IV: Minimal Documentation

MUST: Document ONLY when functionally necessary:

  • Clear interface (expected input/generated output)
  • Single purpose of command
  • Execution pre-conditions (if they exist)

DO NOT: Create additional documentation files

  • ❌ README.md, GUIDE.md, USAGE.md, EXAMPLES.md
  • ❌ "How to use" documentation (this goes in chat/help)
  • ❌ Theoretical concept explanations

DO NOT: Document internals of sub-agents or called resources

Principle V: Token Efficiency

MUST: Direct and concise instructions MUST: Reuse principles from base.md via reference, not duplication MUST: Avoid repeating general rules in each command

DO NOT: Include extensive explanations about basic concepts DO NOT: Repeat file creation policies in each command DO NOT: Duplicate constraints that already exist in principles/

WHEN: Need to reference general principle → USE: "Follow file creation policy (base.md)" → DO NOT: Repeat entire policy in command

Principle VI: Separation of Responsibilities

MUST: Each command documents only its own responsibilities MUST: When using sub-resources, reference only what's necessary for invocation

DO NOT: Describe responsibilities of other resources DO NOT: Create ambiguity between responsibilities of different resources DO NOT: Document workflows of external resources

BENEFIT: Coherent workflows, mitigated risks, zero unnecessary processing

Principle VII: Sub-Agent Invocation

MUST: Reference only WHAT the sub-agent does

  • "Use FileValidator to verify file existence and permissions"
  • "Invoke CodeAnalyzer for complexity metrics"

MUST: Specify only invocation interface (input/output)

DO NOT: Explain HOW the sub-agent works internally DO NOT: Duplicate sub-agent documentation in command DO NOT: Describe algorithms or internal strategies of sub-agent

PATTERN: "Tell, Don't Teach"

  • Tell WHAT the sub-agent does
  • Don't teach HOW it works

Principle VIII: Composition Patterns

WHEN: Complex task requires multiple specialized steps → DO: Invoke specialized sub-agents sequentially → DO: Define clear and explicit execution order → DO: Specify how results from one step feed the next

WHEN: Simple, direct task, no specialization needed → DO: Implement directly in command → DO NOT: Create unnecessary sub-agent for trivial task

PATTERN: Composition > Monolithic

  • Prefer composition of specialized sub-agents
  • Avoid monolithic commands that do "everything"

Principle IX: Input Validation and Error Handling

MUST: Validate critical inputs before processing MUST: Fail fast with clear message when input invalid MUST: Return structured error with sufficient context

DO NOT: Process invalid inputs silently DO NOT: Crash without message or context DO NOT: Return null/undefined without explanation

MUST: Structured error format:

{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "File path required",
    "suggestion": "Provide --file=<path> argument"
  }
}

MUST: Suggest correction when possible MUST: Include context of what caused error

Principle X: Creation Constraints

DO NOT: Create commands to explain concepts

  • Use chat for explanations
  • Commands are to EXECUTE, not TEACH

DO NOT: Create commands with >200 lines of implementation

  • Split into specialized sub-agents
  • Commands should be orchestrators, not complex executors

DO NOT: Create commands that only call a sub-agent

  • If command only does "invoke SubAgent X", it doesn't need to exist
  • Use sub-agent directly or integrate additional logic

MUST: Command adds value beyond simply invoking resource MUST: Each command has clear purpose that justifies its existence

Keywords de Ativação

Esta SKILL ativa quando usuário menciona:

  • "criar comando", "novo comando", "modificar comando"
  • "criar slash command", "implementar comando"
  • "fazer um comando", "gerar comando"

Não ativa para perguntas conceituais sobre Slash Commands.

Versão: 0.0.1-beta (Modular) Parte do: anti-flood plugin