@zigrivers/scaffold 2.1.2 → 2.38.0

package/knowledge/core/claude-md-patterns.md

@@ -0,0 +1,254 @@
+---
+name: claude-md-patterns
+description: Patterns for structuring CLAUDE.md files including section organization, rule authoring, pointer patterns, and merge strategies
+topics: [claude-md, ai-configuration, rule-files, memory-management, project-setup]
+---
+
+# CLAUDE.md Patterns
+
+CLAUDE.md is the primary instruction file for AI coding agents. It is loaded at the start of every session and defines how the agent should behave within a project. A well-structured CLAUDE.md dramatically improves agent adherence; a poorly structured one gets ignored or causes conflicts. This knowledge covers structure, authoring, the pointer pattern, and the merge strategy for multi-step pipeline updates.
+
+## Summary
+
+### Purpose
+
+CLAUDE.md is a project-level instruction file that AI agents (Claude Code, Codex, etc.) read at session start. It answers three questions:
+1. **What are the rules?** — Coding conventions, git workflow, testing requirements
+2. **How do I do common tasks?** — Key commands, PR workflow, deployment
+3. **What should I avoid?** — Anti-patterns, forbidden operations, common pitfalls
+
+### Section Organization
+
+A well-structured CLAUDE.md follows this order, from most-referenced to least:
+
+| Section | Purpose | Example Content |
+|---------|---------|-----------------|
+| **Core Principles** | 3-5 non-negotiable tenets | TDD, simplicity, no laziness |
+| **Project Overview** | What this project is (1-2 sentences) | "Prompt pipeline for scaffolding projects" |
+| **Key Commands** | Commands the agent runs constantly | `make check`, `make test`, `npm run dev` |
+| **Workflow** | How to do common operations | Branch, commit, PR, merge flow |
+| **Structure Quick Reference** | Where files go | Directory table with purpose |
+| **Environment** | Dev setup specifics | Build tool, test runner, linter |
+| **Rules** | Specific do/don't instructions | "Never push to main directly" |
+| **Self-Improvement** | Learning feedback loop | Lessons file, correction capture |
+| **Autonomous Behavior** | What the agent should do proactively | Fix bugs on sight, use subagents |
+| **Doc Lookup Table** | Where to find detailed docs | Question-to-document mapping |
+
+### Rule Authoring Best Practices
+
+Rules must be specific, actionable, and testable:
+
+**Good rules:**
+- "Run `make check` before every commit"
+- "Never push directly to main — always use branch + PR"
+- "Every commit message starts with `[BD-xxx]` task ID"
+
+**Bad rules:**
+- "Write clean code" — what does clean mean?
+- "Be careful with git" — what specific actions to take/avoid?
+- "Follow best practices" — which ones?
+
+### The Pointer Pattern
+
+Reference external docs instead of duplicating content inline:
+
+```markdown
+## Coding Conventions
+See `docs/coding-standards.md` for full reference. Key rules in `.claude/rules/code-style.md`.
+```
+
+This keeps CLAUDE.md under 200 lines (the empirically-validated adherence threshold) while preserving access to detailed docs. The agent reads referenced docs on demand rather than processing everything at session start.
+
+## Deep Guidance
+
+### Section Organization — Extended
+
+#### Front-Loading Critical Information
+
+Agents skim CLAUDE.md. The first 50 lines get the most attention. Place the most violated rules and most-used commands at the top. Core Principles and Key Commands should appear before any detailed documentation.
+
+#### The 200-Line Threshold
+
+Research and practical experience show that agent adherence drops sharply when CLAUDE.md exceeds ~200 lines. Beyond that length, agents start selectively ignoring instructions — particularly those in the middle or bottom of the file.
+
+Strategies to stay under 200 lines:
+- Use the pointer pattern for anything longer than 5 lines
+- Move path-scoped conventions to `.claude/rules/` files
+- Keep tables compact (no verbose descriptions)
+- Eliminate redundancy (same rule stated multiple ways)
+
+#### Section Templates
+
+**Core Principles** — 3-5 tenets, each a single sentence with a bold label:
+```markdown
+## Core Principles
+- **Simplicity First**: Make every change as simple as possible.
+- **TDD Always**: Write failing tests first, then make them pass.
+- **Prove It Works**: Never mark a task complete without demonstrating correctness.
+```
+
+**Key Commands** — Table format, sorted by frequency of use:
+```markdown
+## Key Commands
+| Command | Purpose |
+|---------|---------|
+| `make check` | Run all quality gates |
+| `make test` | Run test suite |
+| `make lint` | Run linters |
+```
+
+**Doc Lookup Table** — Question-to-document mapping:
+```markdown
+## When to Consult Other Docs
+| Question | Document |
+|----------|----------|
+| How do I branch and commit? | `docs/git-workflow.md` |
+| What are the coding conventions? | `docs/coding-standards.md` |
+```
+
+### Rule Authoring — Extended
+
+#### The Testability Criterion
+
+Every rule should be verifiable. If you cannot check whether the rule was followed, the rule is too vague.
+
+| Rule | Testable? | Fix |
+|------|-----------|-----|
+| "Write good tests" | No | "Every new function has at least one unit test" |
+| "Use proper naming" | No | "Use camelCase for variables, PascalCase for types" |
+| "Run `make check` before commits" | Yes | — |
+| "Never commit `.env` files" | Yes | — |
+
+#### Conflict Resolution
+
+Rules can conflict. When they do, the resolution order is:
+1. CLAUDE.md rules override general conventions
+2. More specific rules override more general rules
+3. Later rules override earlier rules (if truly contradictory)
+4. Project-specific rules override ecosystem defaults
+
+Document known conflicts explicitly: "This project uses tabs despite the TypeScript convention of spaces — see `.editorconfig`."
+
+#### Negative Rules vs. Positive Rules
+
+Prefer positive rules ("always do X") over negative rules ("never do Y") when possible. Positive rules tell the agent what to do; negative rules only eliminate one option from an infinite set.
+
+Exception: safety-critical negative rules are valuable. "Never push to main directly" and "Never commit secrets" are clearer as negatives.
+
+### Pointer Pattern — Extended
+
+#### When to Inline vs. Point
+
+| Content Type | Inline in CLAUDE.md | Point to External Doc |
+|-------------|--------------------|-----------------------|
+| Core principles | Yes | No |
+| Key commands table | Yes | No |
+| Workflow summary (5-10 lines) | Yes | Detailed version elsewhere |
+| Coding conventions (full) | No | `docs/coding-standards.md` |
+| Git workflow (full) | No | `docs/git-workflow.md` |
+| Project structure (full) | No | `docs/project-structure.md` |
+| Design system rules | No | `docs/design-system.md` |
+
+The rule: if the content is referenced multiple times per session, inline a summary. If it is referenced occasionally, point to it.
+
+#### Cross-Reference Format
+
+Use consistent pointer format throughout:
+```markdown
+See `docs/coding-standards.md` for full reference.
+```
+
+Not:
+```markdown
+Refer to the coding standards document for more details.
+```
+
+The first format gives the agent an exact file path to read. The second requires the agent to search for the file.
+
+### Merge Strategy for Multi-Step Pipeline Updates
+
+Seven pipeline steps modify CLAUDE.md during project scaffolding. Each step owns specific sections and must not overwrite sections owned by other steps. This section ownership model prevents destructive overwrites when steps execute sequentially.
+
+#### Section Ownership Map
+
+| Pipeline Step | CLAUDE.md Sections Owned | Operation |
+|--------------|-------------------------|-----------|
+| **beads** | Core Principles, Task Management (Beads commands), Self-Improvement, Autonomous Behavior | Creates initial skeleton |
+| **project-structure** | Project Structure Quick Reference | Adds/updates directory table |
+| **dev-env-setup** | Key Commands, Dev Environment | Adds/updates command table and env section |
+| **git-workflow** | Committing and Creating PRs, Parallel Sessions (Worktrees) | Adds/updates workflow sections |
+| **design-system** | Design System, Browser Testing | Adds/updates design system section |
+| **ai-memory-setup** | Pointer restructuring (cross-cutting) | Replaces inline content with pointers to `.claude/rules/` |
+| **automated-pr-review** | Code Review workflow | Adds/updates review workflow section |
+
+#### Merge Rules
+
+1. **Additive by default.** Each step adds its sections without modifying sections owned by other steps. If a section does not exist, create it. If it exists and belongs to this step, update it in-place.
+
+2. **Never delete unrecognized sections.** If CLAUDE.md contains sections not in the ownership map (user customizations, project-specific sections), preserve them. Move them to the end if they conflict with the expected layout, but never remove them.
+
+3. **Beads goes first.** The `beads` step creates the initial CLAUDE.md skeleton. All subsequent steps add to this skeleton. If `beads` was skipped (project does not use Beads), subsequent steps must still create their sections — they just skip the Beads-specific content.
+
+4. **ai-memory-setup is cross-cutting.** Unlike other steps that add sections, `ai-memory-setup` restructures existing sections by replacing inline content blocks with pointer references to `.claude/rules/` files. It operates across sections owned by other steps but only changes the representation (inline → pointer), not the substance.
+
+5. **claude-md-optimization consolidates.** The final consolidation step (`claude-md-optimization`) reviews the accumulated CLAUDE.md, removes redundancy introduced by incremental additions, fixes inconsistencies in terminology, and reorders for scannability. It operates on all sections but does not add new workflow steps or rules — only consolidates and clarifies what exists.
+
+6. **Preserve tracking comments.** Steps that add tracking comments (`<!-- scaffold:step-name v1 YYYY-MM-DD -->`) must preserve comments from other steps. These comments enable update detection.
+
+7. **Update mode is the norm.** After initial creation by `beads`, all subsequent steps operate in update mode. They check for existing content, preserve customizations, and update in-place rather than replacing.
+
+#### Conflict Scenarios
+
+**Two steps reference the same command.** Example: `dev-env-setup` adds `make check` to Key Commands and `git-workflow` references `make check` in the PR workflow. Resolution: the Key Commands table (owned by `dev-env-setup`) is the single source of truth for command definitions. Other sections reference commands but do not redefine them.
+
+**ai-memory-setup restructures a section another step just added.** This is expected and by design. The `ai-memory-setup` step runs after environment steps and converts verbose inline blocks to compact pointer references. The referenced docs must exist before the pointer is valid.
+
+**User adds custom sections between pipeline runs.** Subsequent pipeline steps must detect and preserve custom sections. Use the tracking comment (`<!-- scaffold:step-name -->`) to identify pipeline-managed sections vs. user-added sections.
+
+### Update Mode Handling
+
+#### Detecting Existing Content
+
+Every pipeline step that modifies CLAUDE.md implements mode detection:
+- If the file does not exist → create mode (write full skeleton)
+- If the file exists → update mode (modify owned sections in-place)
+
+Update mode is the common case. After the first `beads` run, every subsequent step encounters an existing CLAUDE.md.
+
+#### Preserving Custom Sections
+
+Users customize CLAUDE.md between pipeline runs. Common customizations:
+- Adding project-specific rules
+- Adding custom command aliases
+- Adding team-specific workflow notes
+- Adding integration-specific sections (deployment, monitoring)
+
+Pipeline steps must preserve all content they do not own. The safest pattern is:
+1. Read the existing CLAUDE.md
+2. Identify sections owned by this step (by heading or tracking comment)
+3. Replace only those sections with updated content
+4. Leave everything else untouched
+
+#### Additive Updates
+
+When updating a section, prefer additive changes over destructive ones:
+- Add new table rows rather than replacing the entire table
+- Add new subsections rather than rewriting the section
+- Append to lists rather than replacing them
+- Only remove content if it is demonstrably wrong or duplicated
+
+### Common Anti-Patterns
+
+**Inline everything.** CLAUDE.md becomes 500+ lines with full coding standards, complete git workflow, entire project structure. Agent adherence drops, load time increases, signal drowns in noise. Fix: use the pointer pattern. Keep CLAUDE.md under 200 lines.
+
+**Stale commands.** Key Commands table references `npm test` but the project switched to `bun test` two months ago. The agent runs the wrong command and wastes a cycle. Fix: keep Key Commands in sync with actual build tool configuration. The `claude-md-optimization` step verifies this.
+
+**Conflicting rules.** CLAUDE.md says "always use conventional commits" in one section and "use `[BD-xxx]` prefix" in another, with no guidance on which takes precedence. Fix: consolidate commit message rules in one place. If both apply, show the combined format: `[BD-42] feat(api): implement endpoint`.
+
+**Redundant instructions.** The same rule appears in Core Principles, Workflow, and Rules sections with slightly different wording. The agent may follow one version and violate another. Fix: state each rule once in its canonical section. Other sections reference it.
+
+**Missing doc lookup.** CLAUDE.md references "the git workflow" but does not specify the file path. The agent searches, guesses, or ignores the reference. Fix: always include exact file paths in references.
+
+**No update mode.** A pipeline step blindly writes a complete CLAUDE.md, overwriting sections added by earlier steps. Fix: every step that modifies CLAUDE.md must read it first, identify its owned sections, and update only those sections.
+
+**Over-specifying autonomous behavior.** CLAUDE.md micro-manages every agent decision: "If you see a typo, fix it. If you see a missing import, add it. If you see..." This wastes lines on things the agent would do anyway. Fix: autonomous behavior should cover non-obvious expectations — "fix bugs on sight," "use subagents for research," "re-plan when stuck." Skip obvious behaviors.

package/knowledge/core/coding-conventions.md

@@ -0,0 +1,246 @@
+---
+name: coding-conventions
+description: Universal coding standards patterns across languages and linter/formatter configuration
+topics: [coding-standards, linting, formatting, naming, error-handling, code-style]
+---
+
+# Coding Conventions
+
+Coding conventions eliminate decision fatigue, reduce code review friction, and make codebases navigable by any team member. Good conventions are enforced by tooling, not willpower. This knowledge covers universal patterns across languages, language-specific catalogs, and the tooling that makes conventions stick.
+
+## Summary
+
+### Categories of Standards
+
+Coding standards fall into six categories, each requiring different enforcement strategies:
+
+1. **Naming Conventions** — Variable, function, class, file, and directory naming patterns. Language-specific (camelCase in JS/TS, snake_case in Python/Go). Enforced by linters.
+2. **Formatting** — Indentation, line length, brace placement, trailing commas, semicolons. Enforced by formatters (Prettier, Black, gofmt). Never debated in code review.
+3. **Error Handling** — How errors are created, propagated, caught, and reported. Language-specific patterns (try/catch, Result types, error returns). Enforced by linters + adherence evals.
+4. **Import Organization** — Ordering (stdlib, third-party, local), grouping, path aliasing. Enforced by linters (eslint-plugin-import, isort).
+5. **Comment Philosophy** — When to comment (why, not what), documentation comments vs inline, TODO format, deprecation markers. Partially enforced by linters.
+6. **Code Structure** — Function length limits, file length guidelines, single responsibility, early returns. Enforced by linters + code review.
+
+### Linter/Formatter Selection
+
+**Rule**: Formatters handle style. Linters handle correctness and patterns. Never configure linter rules that a formatter already handles.
+
+| Language | Formatter | Linter | Config Location |
+|----------|-----------|--------|----------------|
+| TypeScript | Prettier | ESLint (flat config) | `eslint.config.js`, `.prettierrc` |
+| Python | Black / Ruff format | Ruff | `pyproject.toml` |
+| Go | gofmt (built-in) | golangci-lint | `.golangci.yml` |
+| Shell | shfmt | ShellCheck | `.shellcheckrc`, `.editorconfig` |
+| Rust | rustfmt | clippy | `rustfmt.toml`, `clippy.toml` |
+
+### The Golden Rule
+
+If a convention cannot be checked by a tool, it will not be followed consistently. Prefer conventions that can be automated. Document the rest, but accept lower compliance.
+
+### Comment Philosophy at a Glance
+
+Comments explain **why**, not **what**. If you need a comment to explain what code does, the code is too complex — refactor first. Extract well-named functions, use descriptive variables, replace magic numbers with constants. TODOs must include a task ID: `// TODO [BD-123]: Reason`. Bare TODOs are not allowed.
+
+## Deep Guidance
+
+### Language-Specific Convention Catalogs
+
+#### TypeScript / JavaScript
+
+**Naming**: Variables and functions use `camelCase`. Types, interfaces, and classes use `PascalCase`. True constants use `UPPER_SNAKE_CASE`. File names use `kebab-case.ts` for modules, `PascalCase.tsx` for React components. Booleans prefix with `is`, `has`, `can`, `should`. Private class fields use `#` prefix.
+
+**Error handling**: Never catch and swallow — `catch (e) {}` is forbidden. Use custom error classes for domain errors. Never use `any` as a catch-all; use `unknown` and narrow. No `@ts-ignore` without a comment explaining why and linking to an issue.
+
+**Imports**: Order as Node builtins, third-party, path-aliased local (`@/`), relative local. One blank line between groups. Prefer named exports over default exports. Use path aliases over deep relative paths.
+
+**Key ESLint rules**: `no-explicit-any: error`, `no-unused-vars` (with `^_` pattern ignored), `prefer-const: error`, `no-var: error`, `eqeqeq: always`.
+
+#### Python
+
+**Naming**: Variables, functions, methods use `snake_case`. Classes use `PascalCase`. Constants use `UPPER_SNAKE_CASE`. Modules and packages use short `snake_case` names. Type variables use `T`, `K`, `V` or descriptive `UserT`.
+
+**Error handling**: Never bare `except:` — always catch specific exceptions. Use custom exceptions inheriting from a project base exception. Use context managers for resource cleanup. Avoid `assert` in production code (stripped with `-O`).
+
+**Imports**: Order as stdlib, third-party, local (enforced by isort/ruff). No `from module import *`. Absolute imports preferred; relative imports acceptable within a package.
+
+**Ruff config**: Select rules `E, F, W, I, N, UP, B, SIM, T20` covering pycodestyle, pyflakes, isort, naming, pyupgrade, bugbear, simplify, and no-print.
+
+#### Go
+
+**Naming**: Exported identifiers use `PascalCase`, unexported use `camelCase`. Acronyms are all caps (`ID`, `HTTP`, `URL`). Single-method interfaces use method name + `er` suffix (`Reader`, `Writer`). Package names are short, lowercase, no underscores.
+
+**Error handling**: Always check error returns — never discard with `_`. Wrap errors with context: `fmt.Errorf("fetch user %s: %w", id, err)`. Use sentinel errors for expected conditions. Use `errors.Is()` and `errors.As()`, never string comparison. Return errors, don't panic.
+
+**Formatting**: `gofmt` is non-negotiable. Run on save. No style discussions in Go.
+
+**Linter**: Enable `errcheck`, `govet`, `staticcheck`, `unused`, `gosimple`, `ineffassign`, `gocritic` via golangci-lint.
+
+#### Shell (Bash)
+
+**Naming**: Variables use `snake_case`. Constants/environment use `UPPER_SNAKE_CASE`. Functions use `snake_case`. Script files use `kebab-case.sh`.
+
+**Error handling**: Every script starts with `set -euo pipefail`. Use `trap` for cleanup. Quote all variable expansions. Use `[[ ]]` over `[ ]`. Check command existence before use.
+
+**ShellCheck**: Run on all `.sh` files. Address warnings; if a directive is needed, comment why.
+
+### Naming Convention Matrix
+
+| Context | TypeScript | Python | Go |
+|---------|-----------|--------|-----|
+| Local variable | `camelCase` | `snake_case` | `camelCase` |
+| Function/method | `camelCase` | `snake_case` | `PascalCase` (exported) |
+| Class/type | `PascalCase` | `PascalCase` | `PascalCase` |
+| Constant | `UPPER_SNAKE` | `UPPER_SNAKE` | `PascalCase` (exported) |
+| File name | `kebab-case` | `snake_case` | `snake_case` |
+| Database column | `snake_case` | `snake_case` | `snake_case` |
+| Environment var | `UPPER_SNAKE` | `UPPER_SNAKE` | `UPPER_SNAKE` |
+| URL path | `kebab-case` | `kebab-case` | `kebab-case` |
+
+**The context rule**: Follow the convention of the domain you are writing in, not the language you are writing with. Database columns are `snake_case` regardless of whether your ORM is in TypeScript or Go.
+
+### Comment and Documentation Standards
+
+**When to comment**: Explain intent, constraints, and non-obvious decisions. Never narrate code. Bad: `// increment counter` before `counter++`. Good: `// Retry up to 3 times — upstream API has transient 503s during deployments`.
+
+**When code should self-document**: Extract well-named functions instead of commenting blocks. Use descriptive variable names instead of commenting values. Use enums/constants instead of commenting magic numbers.
+
+**Documentation comments**: Public APIs always need documentation comments. TypeScript uses JSDoc `/** */`. Python uses docstrings. Go uses comments above exported identifiers starting with the identifier name.
+
+**TODO format**: `// TODO [BD-123]: Reason for the TODO`. Also `FIXME [BD-456]` and `HACK [BD-789]`. Bare TODOs without task IDs accumulate without accountability and are not allowed.
+
+### Error Handling Patterns by Language
+
+The error handling strategy must be consistent within each architectural layer and documented in `docs/coding-standards.md`.
+
+#### TypeScript Error Pattern
+
+```typescript
+// Domain errors with discriminated unions
+class AppError extends Error {
+  constructor(message: string, public readonly code: string) {
+    super(message);
+    this.name = 'AppError';
+  }
+}
+class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(`${resource} not found: ${id}`, 'NOT_FOUND');
+  }
+}
+
+// Service layer: throw domain errors
+async function getUser(id: string): Promise<User> {
+  const user = await userRepo.findById(id);
+  if (!user) throw new NotFoundError('User', id);
+  return user;
+}
+
+// Controller layer: catch and map to HTTP responses
+app.get('/users/:id', async (req, res) => {
+  try {
+    const user = await getUser(req.params.id);
+    res.json(user);
+  } catch (err) {
+    if (err instanceof NotFoundError) return res.status(404).json({ error: err.message });
+    throw err; // re-throw unexpected errors for global handler
+  }
+});
+```
+
+#### Python Error Pattern
+
+```python
+class AppError(Exception):
+    """Base exception for the application."""
+    def __init__(self, message: str, code: str = "INTERNAL"):
+        super().__init__(message)
+        self.code = code
+
+class NotFoundError(AppError):
+    def __init__(self, resource: str, id: str):
+        super().__init__(f"{resource} not found: {id}", "NOT_FOUND")
+
+# FastAPI exception handler
+@app.exception_handler(NotFoundError)
+async def not_found_handler(request, exc):
+    return JSONResponse(status_code=404, content={"error": str(exc)})
+```
+
+#### Go Error Pattern
+
+```go
+var ErrNotFound = errors.New("not found")
+
+func (r *UserRepo) FindByID(ctx context.Context, id string) (*User, error) {
+    user, err := r.db.QueryRow(ctx, "SELECT ... WHERE id = $1", id)
+    if err != nil {
+        if errors.Is(err, sql.ErrNoRows) {
+            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
+        }
+        return nil, fmt.Errorf("query user %s: %w", id, err)
+    }
+    return user, nil
+}
+```
+
+### Import Organization Details
+
+Consistent import ordering makes files scannable and diffs cleaner. Every language has an established convention:
+
+**TypeScript** (enforced by `eslint-plugin-import`):
+```typescript
+// 1. Node built-ins
+import { readFileSync } from 'fs';
+import path from 'path';
+
+// 2. Third-party packages
+import express from 'express';
+import { z } from 'zod';
+
+// 3. Path-aliased local imports
+import { config } from '@/config/env';
+import { UserService } from '@/features/auth';
+
+// 4. Relative imports
+import { validateInput } from './helpers';
+import type { RequestContext } from './types';
+```
+
+**Python** (enforced by `isort` or `ruff`):
+```python
+# 1. Standard library
+import os
+from pathlib import Path
+
+# 2. Third-party
+from fastapi import Depends
+from sqlalchemy.orm import Session
+
+# 3. Local
+from app.core.config import settings
+from app.services.auth import AuthService
+```
+
+### Linter Configuration Strategies
+
+**Strict from Day One**: Enable all rules at project start. Zero warnings policy. Best for new projects and small teams.
+
+**Progressive Adoption**: Start with formatter + critical rules only. Add rules incrementally. Track `eslint-disable-next-line` counts as a health metric — they should decrease over time, not increase. Best for existing projects and large teams.
+
+**The Warning Trap**: Never leave linter rules as warnings long-term. Warnings are ignored. Either a rule is an error (enforced) or off (not enforced). Warnings create noise without value.
+
+**Monorepo inheritance**: Root config has shared rules. Package configs extend root with package-specific additions. Override blocks handle per-directory exceptions (test files get relaxed rules).
+
+### Common Anti-Patterns
+
+**Inconsistent Naming**: Same concept has different names — `userId`, `user_id`, `UserID`, `uid` in one codebase. Fix: define a naming glossary in `docs/coding-standards.md`. One name for one concept.
+
+**Swallowed Errors**: `catch (e) {}` or `except: pass` discards errors silently. Fix: lint rules that forbid empty catch blocks. If truly intentional, require a justification comment.
+
+**Magic Numbers**: `if (retries > 3)` or `setTimeout(fn, 86400000)` with no context. Fix: extract to named constants. Lint rules can flag numeric literals in conditionals.
+
+**Over-Commenting**: Every line has a comment restating what the code does. Fix: delete comments that restate code. Keep only "why" comments.
+
+**Inconsistent Error Handling**: Some functions throw, some return null, some return error codes. Fix: document one error strategy per architectural layer. Controllers throw HTTP errors. Services return Result types. Repositories throw data access errors.
+
+**Import Chaos**: No ordering, mixed styles, deep relative paths. Fix: configure import-ordering tools (`eslint-plugin-import`, `isort`) and path aliases. Run formatter on save.

package/knowledge/core/database-design.md

@@ -4,6 +4,8 @@ description: Database schema design, normalization, indexing, and migration patt
 topics: [database, schema, sql, nosql, migrations, indexing, data-modeling]
 ---
 
+## Summary
+
 ## From Domain Models to Schema
 
 The domain model defines what the business cares about. The database schema defines how that information is stored. The mapping between them is deliberate, not automatic.
@@ -77,6 +79,8 @@ metadata JSONB NOT NULL DEFAULT '{}'
 
 **Lookup table** — Store value objects with limited valid values in a reference table. Best for enums with associated data (status codes with descriptions, country codes with names).
 
+## Deep Guidance
+
 ### Modeling Relationships
 
 **One-to-one:** Use a foreign key in either table (typically the dependent side). Consider: could this be columns in the same table instead?
@@ -378,3 +382,7 @@ For distributed databases (DynamoDB, Cassandra), the partition key determines da
 **Allowing unbounded growth in aggregate tables.** An events or logs table that grows without limit, eventually consuming all storage and degrading query performance. Fix: define a retention policy and implement it (archival, partitioning, or deletion).
 
 **Using the database as a message queue.** Polling a table for new rows to process. This creates lock contention, wastes resources, and scales poorly. Fix: use a proper message queue (Redis, RabbitMQ, SQS) for event-driven processing.
+
+## See Also
+
+- [domain-modeling](../core/domain-modeling.md) — Domain entities map to database schema