prevent-file-floods

Previne criação desnecessária de arquivos auxiliares/descritivos - chat-first approach com validação semântica

Prevent File Floods

Esta SKILL previne criação desnecessária de arquivos auxiliares/descritivos (análises, relatórios, documentação) provenientes de processamento de IA, mantendo projeto limpo e focado em código funcional.

ATIVAÇÃO: SEMPRE (em todas as interações) PRIORIDADE: 1 (máxima - layer fundamental)

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 Prevenção de File Floods

Principles for File Flood Prevention

Principle I: Validation Logic Inversion

MUST: Validate ONLY problematic files (auxiliary/descriptive) MUST: Create functional files ALWAYS without validation

DO NOT: Validate all files indiscriminately DO NOT: Block creation of functional code, config, or tests

Categorization:

  • Functional files = condition of existence → CREATE automatically
  • Auxiliary files = description of something → VALIDATE user intent

Principle II: Functional Files Whitelist

MUST: Create automatically without validation:

  • Code: .py, .js, .ts, .go, .rs, .java, .cpp, .html, .css
  • Config: package.json, tsconfig.json, .env.example, Dockerfile, Makefile
  • Tests: test_*.py, *.test.ts, *.spec.js, __tests__/**
  • Definitions: SKILL.md, AGENT.md, COMMAND.md
  • Assets: .png, .svg, .woff, fonts, images

REFERENCE: Complete list in functional-files.yaml

LOGIC: If file is condition of existence of project/feature → CREATE

Principle III: Auxiliary Files Validation

MUST: Validate user intent before creating:

  • Docs: README.md, DOCUMENTATION.md, GUIDE.md, TUTORIAL.md
  • Analyses: ANALYSIS.md, REPORT.md, SUMMARY.md, REVIEW.md, NOTES.md
  • Examples: example.py, demo.js, sample.ts (illustrative, not functional)

LOGIC: If file describes/analyzes something existing → VALIDATE before creating

Principle IV: Semantic Analysis of Imperative Command

MUST: Create auxiliary file ONLY if message contains explicit imperative command

Semantic detection (multilingual):

  • COMMAND → CREATE: "Create a file", "Save to file", "Generate document"
  • QUESTION → DO NOT CREATE: "How to create?", "Should I create?"
  • CONDITIONAL → DO NOT CREATE: "If I create...", "When creating..."

MUST: Trust Claude's multilingual understanding DO NOT: Do simple keyword matching DO NOT: Limit detection to English only

WHEN: Doubt about intention → RESPOND: Complete in chat → ASK: "Want to save to file?"

Principle V: Decision Pipeline

MUST: Follow deterministic pipeline:

1. Functional file (whitelist)? → CREATE automatically
2. Auxiliary file + imperative command? → CREATE
3. Auxiliary file without command? → CHAT + ASK user

DO NOT: Deviate from pipeline DO NOT: Create auxiliary files "as precaution" DO NOT: Assume file preference when not specified

Principle VI: Chat-First Default Behavior

DEFAULT: Chat > File

WHEN: User asks for analysis/review/explanation WITHOUT command to create file → RESPOND: Complete in chat with markdown → ASK: "Want me to save this to file?"

EXCEPTION: Functional files

WHEN: Implementing code/config/tests → CREATE: Automatically without asking → EXAMPLES:

  • Code: auth.ts, api.py, UserController.java
  • Config: package.json, .env.example, Dockerfile
  • Tests: test_auth.py, api.test.ts

Principle VII: Special Cases

README.md in new project: MUST: Suggest creating AFTER implementing features DO NOT: Create automatically at start

Unit tests: MUST: Create automatically (they are functional code) DO NOT: Treat as documentation

Inline vs external documentation: MUST: ALWAYS add inline docstrings in code DO NOT: Create external .md file (except imperative command)

Code migration: MUST: Create new functional files automatically DO NOT: Create MIGRATION_REPORT.md or similar

Principle VIII: User Communication

WHEN: Blocking auxiliary file → FORMAT:

[Complete analysis in chat with markdown]

Responded in chat to avoid polluting the project.
Want to save to file? (e.g.: ANALYSIS.md)

WHEN: Suggesting optional file → FORMAT:

Implemented [feature X]:
- src/feature.ts
- src/types/feature.d.ts

Want to also create README.md with instructions?

DO NOT: Use emojis in messages MUST: Be direct and concise in communication

Principle IX: Activation and Priority

MUST: Activate ALWAYS (in all interactions) MUST: Priority 1 (maximum - fundamental layer) MUST: Semantic analysis, not keyword matching MUST: Universal support (all languages supported by Claude)

Principle X: Success Metrics

TARGET: 80-90% reduction in unnecessary auxiliary files TARGET: <1% false positives (block functional file) TARGET: <5% false negatives (create auxiliary without command) TARGET: 95%+ analyses/reviews in chat (not in file)

Self-Check Before Creating File

BEFORE creating any file:

  1. Is it code/config/test? → CREATE
  2. Is it SKILL/AGENT/COMMAND? → CREATE
  3. Is it analysis/doc/example? → VALIDATE imperative command
  4. When in doubt? → ASK user