project-idioms

name	project-idioms
description	Auto-evolved skill containing project-specific architectural idioms extracted from the developer's own code decisions. Generated by skill_evolution.js. Commit this file to share your Engineering Culture across the team. Every agent MUST respect these idioms above generic defaults.
version	auto
last-updated	"2026-04-09T00:00:00.000Z"
digest-cycles	0
pattern	generator
routing	{"domain":"general","tier":"basic"}

Hallucination Traps (Read First)

• ❌ Overriding project idioms without explicit justification -> ✅ Idioms represent team decisions; flag deviations with reasoning
• ❌ Applying idioms from one project to a different project -> ✅ Idioms are project-specific; verify they apply to the current codebase

---

Project Idioms — Auto-Evolved Skill

Authority Level: ABSOLUTE These idioms were extracted from this project's actual code decisions. They override all generic agent defaults and best practices. Every agent reads this file on activation and adapts its proposals accordingly.

---

How Idioms Are Born

1. Developer commits code that differs from what the AI proposed.
2. skill_evolution.js digest extracts the architectural delta (semantic filter).
3. A minimal LLM prompt (< 500 tokens) identifies the WHY behind the change.
4. The idiom is recorded here with a stable pattern + reason pair.
5. All future code generations must align with these idioms.

---

Recorded Idioms

ID	Pattern	Why This Project Uses It	Domain	Since
—	—	No idioms recorded yet. Run your first digest cycle.	—	—

---

How to Add New Idioms

Run after committing or staging a meaningful architectural change:

# Analyze staged changes (default)
node .agent/scripts/skill_evolution.js digest

# Preview without writing
node .agent/scripts/skill_evolution.js digest --dry-run

# Analyze last commit instead of staged
node .agent/scripts/skill_evolution.js digest --head

# Check current idiom count and token savings
node .agent/scripts/skill_evolution.js status

---

Enforcement Rules for All Agents

□ Before proposing any code: scan the idiom table above
□ If your proposal contradicts an idiom → flag it explicitly with:
     "⚠️ Note: My proposal differs from Project Idiom #N. Reason: [explain]"
□ Never override an idiom silently
□ When citing an idiom in a review:
     "Per Project Idiom #N: [pattern] — [reason]"
□ If no idioms yet → proceed with domain-standard approaches

---

Digest History

Last digest: never Total cycles: 0

Run node .agent/scripts/skill_evolution.js status to see full statistics.

---

AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:

1. Over-engineering: Proposing complex abstractions or distributed systems when a simpler approach suffices.
2. Hallucinated Libraries/Methods: Using non-existent methods or packages. Always // VERIFY or check package.json / requirements.txt.
3. Skipping Edge Cases: Writing the "happy path" and ignoring error handling, timeouts, or data validation.
4. Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.
5. Silent Degradation: Catching and suppressing errors without logging or re-raising.

---

Slash command: /review or /tribunal-full Active reviewers: logic-reviewer · security-auditor

❌ Forbidden AI Tropes

1. Blind Assumptions: Never make an assumption without documenting it clearly with // VERIFY: [reason].
2. Silent Degradation: Catching and suppressing errors without logging or handling.
3. Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.

Review these questions before confirming output:

✅ Did I rely ONLY on real, verified tools and methods?
✅ Is this solution appropriately scoped to the user's constraints?
✅ Did I handle potential failure modes and edge cases?
✅ Have I avoided generic boilerplate that doesn't add value?

🛑 Verification-Before-Completion (VBC) Protocol

CRITICAL: You must follow a strict "evidence-based closeout" state machine.

• ❌ Forbidden: Declaring a task complete because the output "looks correct."
• ✅ Required: You are explicitly forbidden from finalizing any task without providing concrete evidence (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.

Pre-Flight Checklist

• Have I reviewed the user's specific constraints and requests?
• Have I checked the environment for relevant existing implementations?

VBC Protocol (Verification-Before-Completion)

You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.

---

🤖 LLM-Specific Traps

AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:

1. Over-engineering: Proposing complex abstractions or distributed systems when a simpler approach suffices.
2. Hallucinated Libraries/Methods: Using non-existent methods or packages. Always // VERIFY or check package.json / requirements.txt.
3. Skipping Edge Cases: Writing the "happy path" and ignoring error handling, timeouts, or data validation.
4. Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.
5. Silent Degradation: Catching and suppressing errors without logging or re-raising.

---

🏛️ Tribunal Integration (Anti-Hallucination)

Slash command: /review or /tribunal-full Active reviewers: logic-reviewer · security-auditor

❌ Forbidden AI Tropes

1. Blind Assumptions: Never make an assumption without documenting it clearly with // VERIFY: [reason].
2. Silent Degradation: Catching and suppressing errors without logging or handling.
3. Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.

✅ Pre-Flight Self-Audit

Review these questions before confirming output:

✅ Did I rely ONLY on real, verified tools and methods?
✅ Is this solution appropriately scoped to the user's constraints?
✅ Did I handle potential failure modes and edge cases?
✅ Have I avoided generic boilerplate that doesn't add value?

🛑 Verification-Before-Completion (VBC) Protocol

CRITICAL: You must follow a strict "evidence-based closeout" state machine.

• ❌ Forbidden: Declaring a task complete because the output "looks correct."
• ✅ Required: You are explicitly forbidden from finalizing any task without providing concrete evidence (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.