cfsa-antigravity 2.19.0 → 2.19.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/template/.agent/kit-sync.md +3 -3
- package/template/.claude/commands/audit-ambiguity-execute.md +6 -0
- package/template/.claude/commands/audit-ambiguity-rubrics.md +6 -0
- package/template/.claude/commands/audit-ambiguity.md +6 -0
- package/template/.claude/commands/bootstrap-agents-fill.md +6 -0
- package/template/.claude/commands/bootstrap-agents-provision.md +6 -0
- package/template/.claude/commands/bootstrap-agents.md +6 -0
- package/template/.claude/commands/create-prd-architecture.md +6 -0
- package/template/.claude/commands/create-prd-compile.md +6 -0
- package/template/.claude/commands/create-prd-design-system.md +6 -0
- package/template/.claude/commands/create-prd-security.md +6 -0
- package/template/.claude/commands/create-prd-stack.md +6 -0
- package/template/.claude/commands/decompose-architecture-structure.md +6 -0
- package/template/.claude/commands/decompose-architecture-validate.md +6 -0
- package/template/.claude/commands/evolve-contract.md +6 -0
- package/template/.claude/commands/evolve-feature-cascade.md +6 -0
- package/template/.claude/commands/evolve-feature-classify.md +6 -0
- package/template/.claude/commands/evolve-feature.md +6 -0
- package/template/.claude/commands/ideate-discover.md +6 -0
- package/template/.claude/commands/ideate-extract.md +6 -0
- package/template/.claude/commands/ideate-validate.md +6 -0
- package/template/.claude/commands/implement-slice-setup.md +6 -0
- package/template/.claude/commands/implement-slice-tdd.md +6 -0
- package/template/.claude/commands/plan-phase-preflight.md +6 -0
- package/template/.claude/commands/plan-phase-write.md +6 -0
- package/template/.claude/commands/propagate-decision-apply.md +6 -0
- package/template/.claude/commands/propagate-decision-scan.md +6 -0
- package/template/.claude/commands/propagate-decision.md +6 -0
- package/template/.claude/commands/remediate-pipeline-assess.md +6 -0
- package/template/.claude/commands/remediate-pipeline-execute.md +6 -0
- package/template/.claude/commands/remediate-pipeline.md +6 -0
- package/template/.claude/commands/remediate-shard-split.md +6 -0
- package/template/.claude/commands/resolve-ambiguity.md +6 -0
- package/template/.claude/commands/setup-workspace-cicd.md +6 -0
- package/template/.claude/commands/setup-workspace-data.md +6 -0
- package/template/.claude/commands/setup-workspace-hosting.md +6 -0
- package/template/.claude/commands/setup-workspace-scaffold.md +6 -0
- package/template/.claude/commands/sync-kit.md +6 -0
- package/template/.claude/commands/update-architecture-map.md +6 -0
- package/template/.claude/commands/validate-phase-quality.md +6 -0
- package/template/.claude/commands/validate-phase-readiness.md +6 -0
- package/template/.claude/commands/verify-infrastructure.md +6 -0
- package/template/.claude/commands/write-architecture-spec-deepen.md +6 -0
- package/template/.claude/commands/write-architecture-spec-design.md +6 -0
- package/template/.claude/commands/write-be-spec-classify.md +6 -0
- package/template/.claude/commands/write-be-spec-write.md +6 -0
- package/template/.claude/commands/write-fe-spec-classify.md +6 -0
- package/template/.claude/commands/write-fe-spec-write.md +6 -0
- package/template/.claude/skills/accessibility/SKILL.md +522 -0
- package/template/.claude/skills/accessibility/references/WCAG.md +162 -0
- package/template/.claude/skills/accessibility/references/ia-spec-checklist.md +35 -0
- package/template/.claude/skills/adversarial-review/SKILL.md +90 -0
- package/template/.claude/skills/antigravity-workflows/SKILL.md +81 -0
- package/template/.claude/skills/antigravity-workflows/resources/implementation-playbook.md +36 -0
- package/template/.claude/skills/api-design-principles/SKILL.md +169 -0
- package/template/.claude/skills/api-design-principles/assets/api-design-checklist.md +155 -0
- package/template/.claude/skills/api-design-principles/assets/rest-api-template.py +182 -0
- package/template/.claude/skills/api-design-principles/references/graphql-schema-design.md +583 -0
- package/template/.claude/skills/api-design-principles/references/rest-best-practices.md +408 -0
- package/template/.claude/skills/api-design-principles/resources/implementation-playbook.md +513 -0
- package/template/.claude/skills/api-versioning/SKILL.md +166 -0
- package/template/.claude/skills/api-versioning/references/typescript.md +157 -0
- package/template/.claude/skills/architecture-mapping/SKILL.md +219 -0
- package/template/.claude/skills/bootstrap-agents/SKILL.md +258 -0
- package/template/.claude/skills/brainstorming/SKILL.md +177 -0
- package/template/.claude/skills/brand-guidelines/SKILL.md +44 -0
- package/template/.claude/skills/clean-code/SKILL.md +196 -0
- package/template/.claude/skills/clean-code/references/typescript.md +126 -0
- package/template/.claude/skills/code-review-pro/SKILL.md +152 -0
- package/template/.claude/skills/concise-planning/SKILL.md +107 -0
- package/template/.claude/skills/cross-layer-consistency/SKILL.md +117 -0
- package/template/.claude/skills/database-schema-design/SKILL.md +205 -0
- package/template/.claude/skills/database-schema-design/references/relational.md +228 -0
- package/template/.claude/skills/deployment-procedures/SKILL.md +241 -0
- package/template/.claude/skills/design-anti-cliche/SKILL.md +159 -0
- package/template/.claude/skills/design-direction/SKILL.md +45 -0
- package/template/.claude/skills/error-handling-patterns/SKILL.md +226 -0
- package/template/.claude/skills/error-handling-patterns/references/go.md +162 -0
- package/template/.claude/skills/error-handling-patterns/references/python.md +262 -0
- package/template/.claude/skills/error-handling-patterns/references/rust.md +112 -0
- package/template/.claude/skills/error-handling-patterns/references/typescript.md +178 -0
- package/template/.claude/skills/find-skills/SKILL.md +145 -0
- package/template/.claude/skills/git-advanced/SKILL.md +972 -0
- package/template/.claude/skills/git-workflow/SKILL.md +420 -0
- package/template/.claude/skills/idea-extraction/SKILL.md +644 -0
- package/template/.claude/skills/logging-best-practices/SKILL.md +192 -0
- package/template/.claude/skills/logging-best-practices/references/go.md +49 -0
- package/template/.claude/skills/logging-best-practices/references/python.md +52 -0
- package/template/.claude/skills/logging-best-practices/references/typescript.md +215 -0
- package/template/.claude/skills/migration-management/SKILL.md +200 -0
- package/template/.claude/skills/migration-management/references/relational.md +214 -0
- package/template/.claude/skills/minimalist-surgical-development/SKILL.md +135 -0
- package/template/.claude/skills/parallel-agents/SKILL.md +165 -0
- package/template/.claude/skills/parallel-debugging/SKILL.md +135 -0
- package/template/.claude/skills/parallel-feature-development/SKILL.md +157 -0
- package/template/.claude/skills/performance-budgeting/SKILL.md +144 -0
- package/template/.claude/skills/pipeline-rubrics/SKILL.md +51 -0
- package/template/.claude/skills/pipeline-rubrics/references/architecture-rubric.md +19 -0
- package/template/.claude/skills/pipeline-rubrics/references/be-rubric.md +21 -0
- package/template/.claude/skills/pipeline-rubrics/references/fe-rubric.md +20 -0
- package/template/.claude/skills/pipeline-rubrics/references/ia-rubric.md +19 -0
- package/template/.claude/skills/pipeline-rubrics/references/scoring.md +32 -0
- package/template/.claude/skills/pipeline-rubrics/references/vision-rubric.md +12 -0
- package/template/.claude/skills/prd-templates/SKILL.md +107 -0
- package/template/.claude/skills/prd-templates/references/architecture-completeness-checklist.md +28 -0
- package/template/.claude/skills/prd-templates/references/architecture-design-template.md +88 -0
- package/template/.claude/skills/prd-templates/references/be-spec-classification.md +41 -0
- package/template/.claude/skills/prd-templates/references/be-spec-template.md +107 -0
- package/template/.claude/skills/prd-templates/references/bootstrap-verification-protocol.md +50 -0
- package/template/.claude/skills/prd-templates/references/constraint-exploration.md +41 -0
- package/template/.claude/skills/prd-templates/references/data-placement-template.md +74 -0
- package/template/.claude/skills/prd-templates/references/decision-confirmation-protocol.md +68 -0
- package/template/.claude/skills/prd-templates/references/decision-propagation.md +121 -0
- package/template/.claude/skills/prd-templates/references/decomposition-templates.md +226 -0
- package/template/.claude/skills/prd-templates/references/deep-ideation-loading-protocol.md +114 -0
- package/template/.claude/skills/prd-templates/references/design-system-decisions.md +198 -0
- package/template/.claude/skills/prd-templates/references/design-system-prerequisite-check.md +18 -0
- package/template/.claude/skills/prd-templates/references/domain-exhaustion-criteria.md +37 -0
- package/template/.claude/skills/prd-templates/references/engagement-tier-protocol.md +58 -0
- package/template/.claude/skills/prd-templates/references/engineering-standards-template.md +126 -0
- package/template/.claude/skills/prd-templates/references/evolution-layer-guidance.md +91 -0
- package/template/.claude/skills/prd-templates/references/expansion-modes.md +27 -0
- package/template/.claude/skills/prd-templates/references/fe-classification-procedures.md +47 -0
- package/template/.claude/skills/prd-templates/references/fe-spec-template.md +90 -0
- package/template/.claude/skills/prd-templates/references/feature-ledger-protocol.md +149 -0
- package/template/.claude/skills/prd-templates/references/folder-seeding-protocol.md +77 -0
- package/template/.claude/skills/prd-templates/references/fractal-cx-template.md +58 -0
- package/template/.claude/skills/prd-templates/references/fractal-feature-template.md +93 -0
- package/template/.claude/skills/prd-templates/references/fractal-node-index-template.md +55 -0
- package/template/.claude/skills/prd-templates/references/gate-applicability.md +92 -0
- package/template/.claude/skills/prd-templates/references/ideation-crosscut-template.md +36 -0
- package/template/.claude/skills/prd-templates/references/ideation-index-template.md +111 -0
- package/template/.claude/skills/prd-templates/references/ideation-meta-template.md +126 -0
- package/template/.claude/skills/prd-templates/references/infrastructure-report-template.md +71 -0
- package/template/.claude/skills/prd-templates/references/input-classification.md +23 -0
- package/template/.claude/skills/prd-templates/references/map-guard-protocol.md +65 -0
- package/template/.claude/skills/prd-templates/references/operational-templates.md +116 -0
- package/template/.claude/skills/prd-templates/references/persona-completeness-gate.md +20 -0
- package/template/.claude/skills/prd-templates/references/placeholder-guard-template.md +21 -0
- package/template/.claude/skills/prd-templates/references/placeholder-workflow-mapping.md +50 -0
- package/template/.claude/skills/prd-templates/references/shard-boundary-analysis.md +103 -0
- package/template/.claude/skills/prd-templates/references/shard-split-remediation.md +157 -0
- package/template/.claude/skills/prd-templates/references/skill-loading-protocol.md +36 -0
- package/template/.claude/skills/prd-templates/references/slice-completion-gates.md +29 -0
- package/template/.claude/skills/prd-templates/references/spec-coverage-sweep.md +44 -0
- package/template/.claude/skills/prd-templates/references/surface-model.md +61 -0
- package/template/.claude/skills/prd-templates/references/tdd-testing-policy.md +39 -0
- package/template/.claude/skills/prd-templates/references/vision-template.md +57 -0
- package/template/.claude/skills/prd-templates/references/workflow-checkpoint-protocol.md +112 -0
- package/template/.claude/skills/prd-templates/references/write-verification-protocol.md +57 -0
- package/template/.claude/skills/prompt-engineer/SKILL.md +203 -0
- package/template/.claude/skills/regex-patterns/SKILL.md +333 -0
- package/template/.claude/skills/regex-patterns/references/go.md +44 -0
- package/template/.claude/skills/regex-patterns/references/javascript.md +63 -0
- package/template/.claude/skills/regex-patterns/references/python.md +77 -0
- package/template/.claude/skills/regex-patterns/references/rust.md +43 -0
- package/template/.claude/skills/resolve-ambiguity/SKILL.md +278 -0
- package/template/.claude/skills/security-scanning-security-hardening/SKILL.md +231 -0
- package/template/.claude/skills/session-continuity/SKILL.md +732 -0
- package/template/.claude/skills/session-continuity/protocols/01-session-resumption.md +38 -0
- package/template/.claude/skills/session-continuity/protocols/02-progress-generation.md +85 -0
- package/template/.claude/skills/session-continuity/protocols/03-progress-update.md +70 -0
- package/template/.claude/skills/session-continuity/protocols/04-pattern-extraction.md +60 -0
- package/template/.claude/skills/session-continuity/protocols/05-session-close.md +37 -0
- package/template/.claude/skills/session-continuity/protocols/06-decision-analysis.md +84 -0
- package/template/.claude/skills/session-continuity/protocols/07-spec-pipeline-generation.md +48 -0
- package/template/.claude/skills/session-continuity/protocols/08-spec-pipeline-update.md +55 -0
- package/template/.claude/skills/session-continuity/protocols/09-parallel-claim.md +122 -0
- package/template/.claude/skills/session-continuity/protocols/10-placeholder-verification-gate.md +83 -0
- package/template/.claude/skills/session-continuity/protocols/11-parallel-synthesis.md +21 -0
- package/template/.claude/skills/session-continuity/protocols/ambiguity-gates.md +48 -0
- package/template/.claude/skills/skill-creator/SKILL.md +203 -0
- package/template/.claude/skills/skill-creator/references/.gitkeep +0 -0
- package/template/.claude/skills/skill-creator/scripts/.gitkeep +0 -0
- package/template/.claude/skills/spec-writing/SKILL.md +110 -0
- package/template/.claude/skills/systematic-debugging/CREATION-LOG.md +119 -0
- package/template/.claude/skills/systematic-debugging/SKILL.md +297 -0
- package/template/.claude/skills/systematic-debugging/condition-based-waiting-example.ts +158 -0
- package/template/.claude/skills/systematic-debugging/condition-based-waiting.md +115 -0
- package/template/.claude/skills/systematic-debugging/defense-in-depth.md +122 -0
- package/template/.claude/skills/systematic-debugging/find-polluter.sh +63 -0
- package/template/.claude/skills/systematic-debugging/root-cause-tracing.md +169 -0
- package/template/.claude/skills/systematic-debugging/test-academic.md +14 -0
- package/template/.claude/skills/systematic-debugging/test-pressure-1.md +58 -0
- package/template/.claude/skills/systematic-debugging/test-pressure-2.md +68 -0
- package/template/.claude/skills/systematic-debugging/test-pressure-3.md +69 -0
- package/template/.claude/skills/tdd-workflow/SKILL.md +186 -0
- package/template/.claude/skills/tdd-workflow/references/typescript.md +231 -0
- package/template/.claude/skills/tech-stack-catalog/SKILL.md +49 -0
- package/template/.claude/skills/tech-stack-catalog/references/constraint-questions.md +237 -0
- package/template/.claude/skills/tech-stack-catalog/references/dev-tooling-decisions.md +37 -0
- package/template/.claude/skills/tech-stack-catalog/references/surface-decision-tables.md +69 -0
- package/template/.claude/skills/technical-writer/SKILL.md +242 -0
- package/template/.claude/skills/testing-strategist/SKILL.md +319 -0
- package/template/.claude/skills/testing-strategist/references/typescript.md +328 -0
- package/template/.claude/skills/verification-before-completion/SKILL.md +97 -0
- package/template/.claude/skills/workflow-automation/SKILL.md +166 -0
- package/template/.claude/skills/workflow-automation/references/inngest.md +88 -0
- package/template/.claude/skills/workflow-automation/references/temporal.md +64 -0
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: concise-planning
|
|
3
|
+
description: "Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist."
|
|
4
|
+
version: 2.0.0
|
|
5
|
+
source: self
|
|
6
|
+
date_added: "2026-02-27"
|
|
7
|
+
date_rewritten: "2026-03-14"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Concise Planning
|
|
11
|
+
|
|
12
|
+
Generate focused, actionable implementation plans that eliminate ambiguity and prevent scope creep.
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- User asks "how should I approach this?" or "can you make a plan for X?"
|
|
17
|
+
- Task involves multiple files or components
|
|
18
|
+
- Work spans more than ~3 logical steps
|
|
19
|
+
- You need to communicate a proposed sequence before executing
|
|
20
|
+
|
|
21
|
+
## When NOT to Use
|
|
22
|
+
|
|
23
|
+
- Task is a single-step operation (just do it)
|
|
24
|
+
- User gave an explicit command with clear intent (just execute)
|
|
25
|
+
- During `/plan-phase` or `/implement-slice` (those have their own planning structure)
|
|
26
|
+
|
|
27
|
+
## Workflow
|
|
28
|
+
|
|
29
|
+
### 1. Scan Context (30 seconds, not 5 minutes)
|
|
30
|
+
|
|
31
|
+
Read only what's necessary:
|
|
32
|
+
- **Project structure** — `ls` the relevant directories
|
|
33
|
+
- **Existing patterns** — check one similar file for conventions
|
|
34
|
+
- **Constraints** — look for test frameworks, linters, type systems in use
|
|
35
|
+
|
|
36
|
+
Do NOT read every file in the project. Do NOT generate a 500-line analysis. Scan, not study.
|
|
37
|
+
|
|
38
|
+
### 2. Ask or Assume
|
|
39
|
+
|
|
40
|
+
- **0 questions** if the task is clear and you have enough context
|
|
41
|
+
- **1 question max** if there's a genuinely blocking ambiguity
|
|
42
|
+
- **Never more than 2** — if you need more, you don't understand the codebase well enough. Go read more code instead of asking.
|
|
43
|
+
|
|
44
|
+
For non-blocking unknowns, state your assumption:
|
|
45
|
+
> "Assuming we want this as a new utility in `lib/` rather than inline — will adjust if you prefer otherwise."
|
|
46
|
+
|
|
47
|
+
### 3. Generate Plan
|
|
48
|
+
|
|
49
|
+
Use this exact structure:
|
|
50
|
+
|
|
51
|
+
```markdown
|
|
52
|
+
## Approach
|
|
53
|
+
|
|
54
|
+
[1-3 sentences: what you'll do and why this approach over alternatives]
|
|
55
|
+
|
|
56
|
+
## Scope
|
|
57
|
+
|
|
58
|
+
**In:**
|
|
59
|
+
- [Specific deliverable 1]
|
|
60
|
+
- [Specific deliverable 2]
|
|
61
|
+
|
|
62
|
+
**Out:**
|
|
63
|
+
- [Explicitly excluded item — prevents scope creep]
|
|
64
|
+
|
|
65
|
+
## Steps
|
|
66
|
+
|
|
67
|
+
1. [Verb] [specific target] — [why, if non-obvious]
|
|
68
|
+
2. [Verb] [specific target]
|
|
69
|
+
3. [Verb] [specific target]
|
|
70
|
+
4. [Verb] [specific target]
|
|
71
|
+
5. Validate: [specific validation command or check]
|
|
72
|
+
|
|
73
|
+
## Assumptions
|
|
74
|
+
|
|
75
|
+
- [Assumption 1 — what you decided without asking]
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### Plan Quality Rules
|
|
79
|
+
|
|
80
|
+
| Rule | Why |
|
|
81
|
+
|------|-----|
|
|
82
|
+
| **6-10 steps** | Fewer = too vague. More = over-planned. |
|
|
83
|
+
| **Verb-first steps** | "Add", "Create", "Refactor", "Test" — not "The component should..." |
|
|
84
|
+
| **Name files and functions** | "Add `validateEmail()` to `lib/validators.ts`" not "add validation" |
|
|
85
|
+
| **One validation step minimum** | Every plan ends with proof it works |
|
|
86
|
+
| **Explicit "Out" scope** | Prevents the plan from growing mid-execution |
|
|
87
|
+
| **No nested sub-plans** | If a step needs sub-steps, it's too big — split it |
|
|
88
|
+
|
|
89
|
+
### Anti-Patterns
|
|
90
|
+
|
|
91
|
+
| Don't | Do |
|
|
92
|
+
|-------|-----|
|
|
93
|
+
| "Research best practices for X" | Just apply the best practice directly in a step |
|
|
94
|
+
| "Consider whether to use A or B" | Pick one, state why, move on |
|
|
95
|
+
| "Set up the project structure" | "Create `src/validators/` with `index.ts` and `email.ts`" |
|
|
96
|
+
| "Write tests" | "Add tests for `validateEmail`: valid input, empty string, missing @, >254 chars" |
|
|
97
|
+
| 20-step plan | 8-step plan with clear scope boundaries |
|
|
98
|
+
| Plan that describes what might happen | Plan that describes what WILL happen |
|
|
99
|
+
|
|
100
|
+
## Output Format
|
|
101
|
+
|
|
102
|
+
Always present the plan in a markdown code block or as structured markdown. Never as prose paragraphs.
|
|
103
|
+
|
|
104
|
+
After presenting the plan, ask one question:
|
|
105
|
+
> "Ready to execute, or want to adjust anything?"
|
|
106
|
+
|
|
107
|
+
Then execute on confirmation — don't re-plan.
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cross-layer-consistency
|
|
3
|
+
description: Systematic methodology for verifying that IA, BE, and FE specification layers are mutually consistent. Covers coverage matrices, field mapping checks, error code propagation, access control consistency, and data contract drift detection.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Cross-Layer Consistency
|
|
7
|
+
|
|
8
|
+
This skill provides the systematic consistency verification pass run by `audit-ambiguity-execute`, `remediate-pipeline-execute`, `propagate-decision-scan`, and `evolve-feature-cascade`, and its output is a set of labeled consistency issues with layer attribution.
|
|
9
|
+
|
|
10
|
+
## When to Use
|
|
11
|
+
|
|
12
|
+
- After all three spec layers (IA, BE, FE) have at least one document written
|
|
13
|
+
- As part of every audit, every remediation, every decision propagation, and every feature evolution cascade
|
|
14
|
+
- As a standalone pre-gate check before advancing any pipeline stage
|
|
15
|
+
|
|
16
|
+
## Instructions
|
|
17
|
+
|
|
18
|
+
### 1. IA → BE Coverage Matrix
|
|
19
|
+
|
|
20
|
+
Open `docs/plans/ia/index.md` to enumerate all IA shards. For each shard, read its data model and state transition sections. Then open `docs/plans/be/` and verify:
|
|
21
|
+
|
|
22
|
+
- Every IA data model entity has a corresponding BE spec section describing its schema, storage contract, and CRUD operations.
|
|
23
|
+
- Every IA state transition has a corresponding BE endpoint that drives it.
|
|
24
|
+
- Every IA user action (described in the interactions section) has a corresponding API contract in the BE spec.
|
|
25
|
+
|
|
26
|
+
Build a coverage table:
|
|
27
|
+
|
|
28
|
+
| IA Shard | IA Section | BE Spec Section | Status |
|
|
29
|
+
|----------|-----------|-----------------|--------|
|
|
30
|
+
| [name] | [section] | [BE section] | ✅ / ❌ |
|
|
31
|
+
|
|
32
|
+
Document each gap as:
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
COVERAGE GAP: IA shard [name] § [section] → no corresponding BE spec section found.
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### 2. BE → FE Field Mapping Check
|
|
39
|
+
|
|
40
|
+
For every BE endpoint documented in `docs/plans/be/`, enumerate all response fields. For each field, verify it appears in `docs/plans/fe/` — in a component prop definition, a display element, a table column, or an explicit "field not rendered" exclusion.
|
|
41
|
+
|
|
42
|
+
Then for each FE component, verify every input prop maps to a BE request field.
|
|
43
|
+
|
|
44
|
+
Build a mapping table:
|
|
45
|
+
|
|
46
|
+
| BE Endpoint | Field | FE Spec Location | Status |
|
|
47
|
+
|-------------|-------|-------------------|--------|
|
|
48
|
+
| [endpoint] | [field] | [FE location] | ✅ / ❌ |
|
|
49
|
+
|
|
50
|
+
Document each gap as:
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
MAPPING GAP: BE endpoint [name] field [field] → not referenced in FE spec.
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### 3. Error Code Consistency Cross-Reference
|
|
57
|
+
|
|
58
|
+
Build an error code table across layers: for every HTTP status code and application error type defined in BE specs, create a row. Then for each row, identify the FE spec location that handles it (error boundary, toast handler, inline error state, retry logic).
|
|
59
|
+
|
|
60
|
+
| BE Endpoint | Error Code | FE Handler | FE Spec Location | Status |
|
|
61
|
+
|-------------|-----------|------------|-------------------|--------|
|
|
62
|
+
| [endpoint] | [code] | [handler] | [location] | ✅ / ❌ |
|
|
63
|
+
|
|
64
|
+
Any BE error code with no corresponding FE entry is a gap. Document as:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
CONSISTENCY ISSUE: BE § [endpoint] error [code] ↔ FE — no handling found — remediation: add [code] handler to [FE spec section].
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### 4. Access Control Propagation Check
|
|
71
|
+
|
|
72
|
+
For every access control rule defined in IA shards (role-resource-operation triplets), verify the rule appears in both:
|
|
73
|
+
|
|
74
|
+
- **BE**: as a middleware guard, route-level permission check, or explicit authorization step in the endpoint contract.
|
|
75
|
+
- **FE**: as a conditional render, route guard, or disabled state on the triggering UI element.
|
|
76
|
+
|
|
77
|
+
A rule missing from either layer is a gap. Document as:
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
CONSISTENCY ISSUE: IA § [access control section] permission [role→resource:operation] ↔ [BE or FE] — not found — remediation: add guard to [target layer § section].
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### 5. Data Contract Drift Detection
|
|
84
|
+
|
|
85
|
+
When invoked in the context of a schema change (e.g., after `evolve-contract` or a `propagate-decision` run), scan all files under `docs/plans/` for references to the changed type, field name, or validation rule. Check for:
|
|
86
|
+
|
|
87
|
+
- Field name string matches
|
|
88
|
+
- Type annotation references
|
|
89
|
+
- Validation rule references
|
|
90
|
+
|
|
91
|
+
For each file that references the old definition and has not been updated, document as:
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
CONSISTENCY ISSUE: [source layer] § [section] ↔ [target file] § [section] — [field/type] changed in source but not reflected in target — remediation: update [target] to match [source].
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### 6. Documenting Inconsistencies
|
|
98
|
+
|
|
99
|
+
All consistency issues must be written using this exact format:
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
CONSISTENCY ISSUE: [source layer] § [section] ↔ [target layer] § [section] — [what is inconsistent] — [remediation: update [target] to match [source] OR raise for user decision]
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
- **Source layer** is the authoritative layer (the one that should not change).
|
|
106
|
+
- **Target layer** is the one that needs updating.
|
|
107
|
+
- When it is unclear which layer is authoritative, write `raise for user decision` as the remediation and present both versions to the user. Never silently pick one.
|
|
108
|
+
|
|
109
|
+
## Anti-Patterns
|
|
110
|
+
|
|
111
|
+
- **One-direction-only checking** — Checking only one direction of the matrix (IA→BE but not BE→IA). Coverage gaps exist in both directions.
|
|
112
|
+
- **Skipping the error code table** — Skipping the error code table because "the FE will just show a generic error." Every BE error code must have an explicit FE handling specification.
|
|
113
|
+
- **Treating access control propagation as optional** — Treating access control propagation as optional when the spec "looks simple." Missing FE route guards are a security gap, not a style preference.
|
|
114
|
+
|
|
115
|
+
## Related Skills
|
|
116
|
+
|
|
117
|
+
- **`resolve-ambiguity`** — Hand off to `resolve-ambiguity` when a consistency issue cannot be resolved by simply updating the target layer to match the source. Specifically: when both layers present plausible but conflicting definitions and it is unclear which is authoritative, or when the inconsistency reveals a gap that requires new information from the user. This skill detects *what is inconsistent*; `resolve-ambiguity` determines *what the correct answer should be* through its tiered information-gathering methodology.
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: database-schema-design
|
|
3
|
+
description: Design database schemas with normalization, relationships, and constraints. Use when creating new database schemas, designing tables, or planning data models for any database paradigm.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Database Schema Design
|
|
7
|
+
|
|
8
|
+
## Overview
|
|
9
|
+
|
|
10
|
+
Design scalable, well-structured database schemas with proper relationships, constraints, and data types. This skill covers universal data modeling principles. For paradigm-specific patterns, see references.
|
|
11
|
+
|
|
12
|
+
## When to Use
|
|
13
|
+
|
|
14
|
+
- New database schema design
|
|
15
|
+
- Data model planning
|
|
16
|
+
- Relationship design (1:1, 1:N, N:N, graph edges)
|
|
17
|
+
- Normalization or denormalization analysis
|
|
18
|
+
- Constraint and validation planning
|
|
19
|
+
- Performance optimization at schema level
|
|
20
|
+
- Cross-store entity consistency
|
|
21
|
+
|
|
22
|
+
## Paradigm-Specific References
|
|
23
|
+
|
|
24
|
+
After reading the methodology below, read the reference matching your surface's Databases column in the surface stack map (`.agent/instructions/tech-stack.md`):
|
|
25
|
+
|
|
26
|
+
| Paradigm | Reference | Example Stores |
|
|
27
|
+
|----------|-----------|----------------|
|
|
28
|
+
| Relational | `references/relational.md` | PostgreSQL, MySQL, SQLite |
|
|
29
|
+
| Document | `references/document.md` | MongoDB, Firestore, CouchDB |
|
|
30
|
+
| Graph | `references/graph.md` | SurrealDB, Neo4j, ArangoDB |
|
|
31
|
+
| Key-Value | `references/key-value.md` | Redis, DynamoDB, Memcached |
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Universal Data Modeling Principles
|
|
36
|
+
|
|
37
|
+
### 1. Entity Identification
|
|
38
|
+
|
|
39
|
+
Start with the domain:
|
|
40
|
+
1. **Identify nouns** — these become entities/tables/collections
|
|
41
|
+
2. **Identify relationships** — how entities connect
|
|
42
|
+
3. **Identify attributes** — what data each entity holds
|
|
43
|
+
4. **Identify cardinality** — one-to-one, one-to-many, many-to-many
|
|
44
|
+
|
|
45
|
+
### 2. Normalization vs Denormalization
|
|
46
|
+
|
|
47
|
+
**Normalization** reduces data duplication at the cost of join complexity:
|
|
48
|
+
- **1NF** — Eliminate repeating groups (no arrays/CSVs in a single field)
|
|
49
|
+
- **2NF** — Remove partial dependencies (every non-key attribute depends on the WHOLE key)
|
|
50
|
+
- **3NF** — Remove transitive dependencies (non-key attributes don't depend on each other)
|
|
51
|
+
|
|
52
|
+
**Denormalization** trades storage for read performance:
|
|
53
|
+
- Embed frequently co-read data together
|
|
54
|
+
- Pre-compute aggregates for dashboards
|
|
55
|
+
- Duplicate data intentionally (with consistency strategy)
|
|
56
|
+
|
|
57
|
+
**Decision framework:**
|
|
58
|
+
- Write-heavy, consistency-critical → normalize
|
|
59
|
+
- Read-heavy, latency-sensitive → denormalize
|
|
60
|
+
- Mixed → normalize core, denormalize read models
|
|
61
|
+
|
|
62
|
+
### 3. Relationship Patterns
|
|
63
|
+
|
|
64
|
+
| Pattern | Relational | Document | Graph |
|
|
65
|
+
|---------|-----------|----------|-------|
|
|
66
|
+
| **One-to-One** | Foreign key with UNIQUE | Embed subdocument | Edge with cardinality constraint |
|
|
67
|
+
| **One-to-Many** | Foreign key on child | Embed array OR reference | Edge from parent to children |
|
|
68
|
+
| **Many-to-Many** | Junction/join table | Array of references on both sides | Direct edges |
|
|
69
|
+
| **Hierarchical** | Self-referencing FK | Nested documents | Recursive graph traversal |
|
|
70
|
+
|
|
71
|
+
### 4. Access Pattern Design
|
|
72
|
+
|
|
73
|
+
Schema design is driven by how data is **queried**, not just how it's structured:
|
|
74
|
+
|
|
75
|
+
1. **List your read queries** — what does the UI need to display?
|
|
76
|
+
2. **List your write queries** — what creates/updates data?
|
|
77
|
+
3. **Design schema to serve the reads** — not the other way around
|
|
78
|
+
4. **Index for query patterns** — not for every possible query
|
|
79
|
+
|
|
80
|
+
### 5. Constraint Strategy
|
|
81
|
+
|
|
82
|
+
Every schema must enforce:
|
|
83
|
+
- **Required fields** — NOT NULL / required validators
|
|
84
|
+
- **Uniqueness** — unique constraints on natural keys (email, SKU, slug)
|
|
85
|
+
- **Referential integrity** — foreign keys, references, or application-level checks
|
|
86
|
+
- **Domain constraints** — CHECK constraints, enums, value ranges
|
|
87
|
+
- **Cascade behavior** — what happens when parent is deleted (CASCADE, SET NULL, RESTRICT)
|
|
88
|
+
|
|
89
|
+
### 6. ID Strategy
|
|
90
|
+
|
|
91
|
+
| Strategy | When to Use |
|
|
92
|
+
|----------|-------------|
|
|
93
|
+
| **UUID v4** | Default choice. No ordering, globally unique, no collision |
|
|
94
|
+
| **UUID v7** | When you need time-sortable UUIDs (better index performance) |
|
|
95
|
+
| **Auto-increment** | Simple cases, single-database, non-distributed |
|
|
96
|
+
| **ULID** | Time-sortable, lexicographically sortable, URL-safe |
|
|
97
|
+
| **Natural key** | When domain provides a unique identifier (ISBN, SSN) — use with caution |
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Schema Design Checklist
|
|
102
|
+
|
|
103
|
+
- [ ] Identify entities and relationships
|
|
104
|
+
- [ ] Choose ID strategy
|
|
105
|
+
- [ ] Apply normalization rules (or consciously denormalize with rationale)
|
|
106
|
+
- [ ] Define primary keys for all entities
|
|
107
|
+
- [ ] Create foreign keys / references for relationships
|
|
108
|
+
- [ ] Add constraints for data integrity
|
|
109
|
+
- [ ] Select appropriate data types
|
|
110
|
+
- [ ] Plan indexes for common queries
|
|
111
|
+
- [ ] Design for scalability
|
|
112
|
+
- [ ] Document entity purposes and relationships
|
|
113
|
+
- [ ] Plan for schema evolution
|
|
114
|
+
|
|
115
|
+
## Common Pitfalls
|
|
116
|
+
|
|
117
|
+
❌ Don't skip normalization for convenience
|
|
118
|
+
❌ Don't use unbounded text types for all string fields
|
|
119
|
+
❌ Don't forget referential integrity constraints
|
|
120
|
+
❌ Don't use mutable natural keys as primary keys
|
|
121
|
+
❌ Don't store computed values without a cache invalidation strategy
|
|
122
|
+
❌ Don't design schema without knowing query patterns
|
|
123
|
+
|
|
124
|
+
✅ DO use UUIDs or equivalent for primary keys
|
|
125
|
+
✅ DO normalize data unless you have a measured performance reason not to
|
|
126
|
+
✅ DO add validation constraints at the schema level
|
|
127
|
+
✅ DO index foreign keys and common query fields
|
|
128
|
+
✅ DO use timestamps for audit trails
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Persistence Map Interview
|
|
133
|
+
|
|
134
|
+
This interview runs during `/create-prd-stack` Sub-steps A–E. It maps every feature to its query types, then selects the right store for each query type.
|
|
135
|
+
|
|
136
|
+
### Sub-step A — Feature-to-Query Table
|
|
137
|
+
|
|
138
|
+
Walk through every major feature in `ideation-index.md` and ask: "What does this feature need to find, store, relate, and rank/search?"
|
|
139
|
+
|
|
140
|
+
Build the following table:
|
|
141
|
+
|
|
142
|
+
| Feature | Find | Store | Relate | Rank/Search |
|
|
143
|
+
|---------|------|-------|--------|-------------|
|
|
144
|
+
| (from ideation-index.md) | … | … | … | … |
|
|
145
|
+
|
|
146
|
+
Present and confirm the table with the user before proceeding to Sub-step B.
|
|
147
|
+
|
|
148
|
+
### Sub-step B — Registry-First Skill Search
|
|
149
|
+
|
|
150
|
+
Before presenting any store options, read `.agent/skills/find-skills/SKILL.md` and run `npx skills find [query type or store name]` for each query type that appeared in the table.
|
|
151
|
+
|
|
152
|
+
If the registry returns a skill, install it first. The bundled skill library is a fallback only.
|
|
153
|
+
|
|
154
|
+
### Sub-step C — Store Selection Per Query Type
|
|
155
|
+
|
|
156
|
+
Present store options only for query types that appeared in the table:
|
|
157
|
+
|
|
158
|
+
- Skip `DATABASE_VECTOR` if no Rank/Search requirement appeared.
|
|
159
|
+
- Skip `DATABASE_GRAPH` if no Relate requirement appeared.
|
|
160
|
+
|
|
161
|
+
Use constraint-first per-axis flow: constraint questions → filter → present → confirm.
|
|
162
|
+
|
|
163
|
+
### Sub-step D — Bootstrap Per Confirmed Store
|
|
164
|
+
|
|
165
|
+
For each confirmed store, fire bootstrap with its specific sub-key:
|
|
166
|
+
|
|
167
|
+
- e.g., `DATABASE_PRIMARY=PostgreSQL`, `DATABASE_VECTOR=Qdrant`
|
|
168
|
+
- One bootstrap call per sub-key.
|
|
169
|
+
- Each confirmation adds a database skill to the Databases column of the relevant surface row in the surface stack map.
|
|
170
|
+
|
|
171
|
+
### Sub-step E — Write Persistence Map
|
|
172
|
+
|
|
173
|
+
After all stores are confirmed, write to `docs/plans/architecture-draft.md` as a locked section titled `## Persistence Map`.
|
|
174
|
+
|
|
175
|
+
Must include:
|
|
176
|
+
- The feature-to-query table from Sub-step A
|
|
177
|
+
- A mapping of each query type to its canonical store with rationale
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## Cross-Store Entity Consistency Protocol
|
|
182
|
+
|
|
183
|
+
### Triggering Rule
|
|
184
|
+
|
|
185
|
+
This protocol runs for every entity that spans more than one store.
|
|
186
|
+
|
|
187
|
+
### The 4 Questions
|
|
188
|
+
|
|
189
|
+
For each cross-store entity, answer the following in order:
|
|
190
|
+
|
|
191
|
+
1. **Canonical ID** — Single identifier tying representations together. Must be the primary store's UUID stored as a property in every other store — never the graph store's or vector store's internal ID.
|
|
192
|
+
|
|
193
|
+
2. **Creation sequence** — Which store is written first. Recovery mechanism for partial write failures (Saga pattern, compensating transaction, or async retry queue — name which).
|
|
194
|
+
|
|
195
|
+
3. **Deletion cascade** — Cleanup order, mechanism (application-layer sequential deletes, DB-level triggers, or background job — name which).
|
|
196
|
+
|
|
197
|
+
4. **Read strategy** — Whether a read requires data from multiple stores. Name the application-layer join pattern explicitly.
|
|
198
|
+
|
|
199
|
+
### Skill Instruction
|
|
200
|
+
|
|
201
|
+
Read all database skills listed in the Databases column of the surface stack map (`.agent/instructions/tech-stack.md`) for advice on each store's transaction semantics and consistency guarantees before completing this step.
|
|
202
|
+
|
|
203
|
+
### Output
|
|
204
|
+
|
|
205
|
+
Write the completed cross-store consistency table to `architecture-draft.md` as part of the `## Data Strategy` section.
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
# Relational Database Schema Patterns
|
|
2
|
+
|
|
3
|
+
Paradigm-specific patterns for the `database-schema-design` skill. Read `SKILL.md` first for universal methodology.
|
|
4
|
+
|
|
5
|
+
Covers: **PostgreSQL**, **MySQL**, **SQLite**
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Normalization Examples
|
|
10
|
+
|
|
11
|
+
### First Normal Form (1NF) — Eliminate Repeating Groups
|
|
12
|
+
|
|
13
|
+
```sql
|
|
14
|
+
-- NOT 1NF: repeating group in single column
|
|
15
|
+
CREATE TABLE orders_bad (
|
|
16
|
+
id UUID PRIMARY KEY,
|
|
17
|
+
customer_name VARCHAR(255),
|
|
18
|
+
product_ids VARCHAR(255) -- "1,2,3" - repeating group
|
|
19
|
+
);
|
|
20
|
+
|
|
21
|
+
-- 1NF: separate table for repeating data
|
|
22
|
+
CREATE TABLE orders (
|
|
23
|
+
id UUID PRIMARY KEY,
|
|
24
|
+
customer_name VARCHAR(255),
|
|
25
|
+
created_at TIMESTAMP DEFAULT NOW()
|
|
26
|
+
);
|
|
27
|
+
|
|
28
|
+
CREATE TABLE order_items (
|
|
29
|
+
id UUID PRIMARY KEY,
|
|
30
|
+
order_id UUID NOT NULL,
|
|
31
|
+
product_id UUID NOT NULL,
|
|
32
|
+
quantity INTEGER NOT NULL,
|
|
33
|
+
FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE
|
|
34
|
+
);
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### Second Normal Form (2NF) — Remove Partial Dependencies
|
|
38
|
+
|
|
39
|
+
```sql
|
|
40
|
+
-- 2NF: separate tables for partial deps
|
|
41
|
+
CREATE TABLE enrollments (
|
|
42
|
+
id UUID PRIMARY KEY,
|
|
43
|
+
student_id UUID NOT NULL,
|
|
44
|
+
course_id UUID NOT NULL,
|
|
45
|
+
FOREIGN KEY (student_id) REFERENCES students(id),
|
|
46
|
+
FOREIGN KEY (course_id) REFERENCES courses(id),
|
|
47
|
+
UNIQUE(student_id, course_id)
|
|
48
|
+
);
|
|
49
|
+
|
|
50
|
+
CREATE TABLE courses (
|
|
51
|
+
id UUID PRIMARY KEY,
|
|
52
|
+
name VARCHAR(255),
|
|
53
|
+
professor_id UUID NOT NULL,
|
|
54
|
+
FOREIGN KEY (professor_id) REFERENCES professors(id)
|
|
55
|
+
);
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Third Normal Form (3NF) — Remove Transitive Dependencies
|
|
59
|
+
|
|
60
|
+
```sql
|
|
61
|
+
-- 3NF: separate lookup tables
|
|
62
|
+
CREATE TABLE states (
|
|
63
|
+
id UUID PRIMARY KEY,
|
|
64
|
+
code VARCHAR(2) UNIQUE,
|
|
65
|
+
name VARCHAR(100),
|
|
66
|
+
tax_rate DECIMAL(5,3)
|
|
67
|
+
);
|
|
68
|
+
|
|
69
|
+
CREATE TABLE orders (
|
|
70
|
+
id UUID PRIMARY KEY,
|
|
71
|
+
customer_city VARCHAR(100),
|
|
72
|
+
state_id UUID NOT NULL,
|
|
73
|
+
FOREIGN KEY (state_id) REFERENCES states(id)
|
|
74
|
+
);
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Relationship Patterns
|
|
80
|
+
|
|
81
|
+
### One-to-Many
|
|
82
|
+
|
|
83
|
+
```sql
|
|
84
|
+
CREATE TABLE users (
|
|
85
|
+
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
86
|
+
email VARCHAR(255) UNIQUE NOT NULL,
|
|
87
|
+
name VARCHAR(255) NOT NULL,
|
|
88
|
+
created_at TIMESTAMP DEFAULT NOW()
|
|
89
|
+
);
|
|
90
|
+
|
|
91
|
+
CREATE TABLE orders (
|
|
92
|
+
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
93
|
+
user_id UUID NOT NULL,
|
|
94
|
+
order_date TIMESTAMP DEFAULT NOW(),
|
|
95
|
+
total DECIMAL(10,2),
|
|
96
|
+
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
|
|
97
|
+
);
|
|
98
|
+
CREATE INDEX idx_orders_user_id ON orders(user_id);
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### One-to-One
|
|
102
|
+
|
|
103
|
+
```sql
|
|
104
|
+
CREATE TABLE user_profiles (
|
|
105
|
+
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
106
|
+
user_id UUID UNIQUE NOT NULL,
|
|
107
|
+
bio TEXT,
|
|
108
|
+
avatar_url VARCHAR(500),
|
|
109
|
+
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
|
|
110
|
+
);
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Many-to-Many (Junction Table)
|
|
114
|
+
|
|
115
|
+
```sql
|
|
116
|
+
CREATE TABLE course_enrollments (
|
|
117
|
+
id UUID PRIMARY KEY,
|
|
118
|
+
student_id UUID NOT NULL,
|
|
119
|
+
course_id UUID NOT NULL,
|
|
120
|
+
enrolled_at TIMESTAMP DEFAULT NOW(),
|
|
121
|
+
FOREIGN KEY (student_id) REFERENCES students(id) ON DELETE CASCADE,
|
|
122
|
+
FOREIGN KEY (course_id) REFERENCES courses(id) ON DELETE CASCADE,
|
|
123
|
+
UNIQUE(student_id, course_id)
|
|
124
|
+
);
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## Constraint Strategy
|
|
130
|
+
|
|
131
|
+
```sql
|
|
132
|
+
-- NOT NULL, UNIQUE, CHECK, DEFAULT
|
|
133
|
+
CREATE TABLE products (
|
|
134
|
+
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
135
|
+
name VARCHAR(255) NOT NULL,
|
|
136
|
+
sku VARCHAR(100) NOT NULL UNIQUE,
|
|
137
|
+
price DECIMAL(10,2) NOT NULL CHECK (price > 0),
|
|
138
|
+
status VARCHAR(20) NOT NULL CHECK (status IN ('active', 'archived', 'draft'))
|
|
139
|
+
);
|
|
140
|
+
|
|
141
|
+
CREATE TABLE audit_logs (
|
|
142
|
+
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
143
|
+
table_name VARCHAR(100) NOT NULL,
|
|
144
|
+
operation VARCHAR(10) NOT NULL,
|
|
145
|
+
user_id UUID,
|
|
146
|
+
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
|
147
|
+
);
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Data Type Selection
|
|
153
|
+
|
|
154
|
+
### PostgreSQL
|
|
155
|
+
|
|
156
|
+
```sql
|
|
157
|
+
CREATE TABLE users (
|
|
158
|
+
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
159
|
+
email VARCHAR(255),
|
|
160
|
+
name TEXT,
|
|
161
|
+
age SMALLINT,
|
|
162
|
+
balance DECIMAL(15,2), -- Financial data (precise)
|
|
163
|
+
is_active BOOLEAN DEFAULT true,
|
|
164
|
+
birth_date DATE,
|
|
165
|
+
last_login TIMESTAMP WITH TIME ZONE,
|
|
166
|
+
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
167
|
+
metadata JSONB,
|
|
168
|
+
tags TEXT[] DEFAULT ARRAY[]::TEXT[] -- PostgreSQL arrays
|
|
169
|
+
);
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
### MySQL
|
|
173
|
+
|
|
174
|
+
```sql
|
|
175
|
+
CREATE TABLE users (
|
|
176
|
+
id CHAR(36) PRIMARY KEY, -- UUID as CHAR
|
|
177
|
+
email VARCHAR(255),
|
|
178
|
+
name VARCHAR(255),
|
|
179
|
+
age TINYINT UNSIGNED,
|
|
180
|
+
balance DECIMAL(15,2),
|
|
181
|
+
is_active BOOLEAN DEFAULT true,
|
|
182
|
+
birth_date DATE,
|
|
183
|
+
last_login TIMESTAMP,
|
|
184
|
+
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
185
|
+
metadata JSON,
|
|
186
|
+
KEY idx_email (email)
|
|
187
|
+
);
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## Schema Evolution
|
|
193
|
+
|
|
194
|
+
```sql
|
|
195
|
+
-- Add column with default (backward compatible)
|
|
196
|
+
ALTER TABLE users ADD COLUMN phone VARCHAR(20);
|
|
197
|
+
|
|
198
|
+
-- Add constraint on new column
|
|
199
|
+
ALTER TABLE orders ADD CONSTRAINT check_notes CHECK (LENGTH(notes) <= 500);
|
|
200
|
+
|
|
201
|
+
-- Deprecate column safely
|
|
202
|
+
ALTER TABLE users RENAME COLUMN old_field TO old_field_deprecated;
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## Performance: Partitioning
|
|
208
|
+
|
|
209
|
+
```sql
|
|
210
|
+
-- PostgreSQL: Partition by date range for time-series data
|
|
211
|
+
CREATE TABLE events (
|
|
212
|
+
id UUID PRIMARY KEY,
|
|
213
|
+
user_id UUID NOT NULL,
|
|
214
|
+
event_type VARCHAR(100),
|
|
215
|
+
created_at TIMESTAMP NOT NULL
|
|
216
|
+
) PARTITION BY RANGE (DATE_TRUNC('month', created_at));
|
|
217
|
+
|
|
218
|
+
CREATE TABLE events_2024_01 PARTITION OF events
|
|
219
|
+
FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## Resources
|
|
225
|
+
|
|
226
|
+
- [PostgreSQL Data Types](https://www.postgresql.org/docs/current/datatype.html)
|
|
227
|
+
- [MySQL Data Types](https://dev.mysql.com/doc/refman/8.0/en/data-types.html)
|
|
228
|
+
- [Database Normalization Guide](https://en.wikipedia.org/wiki/Database_normalization)
|