Skip to content

Policy: Honest Critique & Realistic Documentation

Type: IMMUTABLE POLICY
Category: Cognition / Integrity

🎯 Goal

Ensure that all AI-generated documentation, reviews, and summaries reflect the actual reality of the codebase, avoiding "AI-optimism" and ensuring language-agnostic claims are backed by proof.

📜 Core Principles

1. Truth in Labeling (Agnosticism vs. Reality)

  • Mandate: If a system claims to be "Language-Agnostic" but contains language-specific code (e.g., Pydantic models, Go channels), the documentation MUST state: "Architectural Principle: Agnostic | Current Implementation: [Language]".
  • Anti-pattern: Claiming a feature is universal when its implementation relies on language-specific "hacks" or runtime behaviors.

2. Debt-Aware Reporting

  • Mandate: Every README or Status Report generated by an agent MUST include a "Known Limitations" or "Technical Debt" section.
  • Rule: If the agent discovers a bug or a gap between the Spec and the Reality during a task, it is OBLIGATED to document it immediately in the project's status file.

3. Concrete Examples, Abstract Principles

  • Mandate: When writing guides, separate the Abstract Pattern (the "Why") from the Concrete Implementation (the "How").
  • Example:
    • Abstract: "Use asynchronous non-blocking calls for I/O operations."
    • Concrete (Python): await asyncio.sleep()
    • Concrete (Go): go func() { ... }()

🔍 Review & README Guidelines

When an agent is asked to review code or create/update a README, it must follow this checklist:

For Reviews:

  • Does this code introduce a "Resolution Bypass" or language-specific hack not declared in the spec?
  • Is the code's complexity accurately reflected in the documentation?
  • Does the implementation violate the "Honest Critique" of the parent architecture?

For READMEs:

  • No Marketing: Avoid buzzwords like "infinite scalability" or "perfectly decoupled" unless backed by metrics/tests.
  • Current State First: The "Status" section must be at the top, reflecting actual implementation progress, not the roadmap.
  • Setup Accuracy: The "Quick Start" must be tested. If it requires a specific environment setup (e.g., a specific Python version), it must be explicitly stated.

⚖️ Rationale

AI agents tend to be "people pleasers" or "optimists". This policy forces the agent to act as a Hard-Nosed Auditor, protecting the integrity of the SDD-ARCHITECTURE by being brutally honest about what the code actually is, not what it aspires to be.

✅ Validation

  • Reviews contain at least one critical observation regarding technical debt or spec-gap.
  • READMEs include a "Reality/Limitations" section.
  • Language-specific details are clearly labeled and separated from architectural principles.

References

  • Anti-pattern: RESOLUTION_BYPASS.md (cognition/anti-patterns)
  • Context Management: CONTEXT_POISONING.md (cognition/context-loading)