docs: ADR-0002 + config guide for preset-based semantic explosion (#17)#21
Merged
Conversation
Record the preset/rule-engine design as ADR-0002: presets supersede profiles and carry option defaults + path-anchored rules; the ForceExtract and Sidecar actions; the local per-scalar fidelity guard and the two yaml.v3 invariants it rests on; the split: config precedence; and verify running the real preset. Notes what was deferred (user-definable rules, more sidecars, nested identity paths). Update the config guide and README to document the actual shipped behavior: --preset (and deprecated --profile), --no-sidecar, the split: config block, and the quicksight semantic layout — sheets to folders, subcomponent categories to files, and dataset SQL to readable .sql sidecars. Fixes the now-stale claims that visuals stay inline at the default depth. Closes #17. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Documents the preset-based “semantic explosion” design and updates user-facing docs to match the shipped QuickSight preset behavior (sheet foldering, per-subcomponent files, and SQL sidecars), including adding a new ADR to record the architectural decision.
Changes:
- Add ADR-0002 describing the preset + rule-engine architecture, sidecar action, and fidelity guard constraints.
- Update the configuration guide to document
--preset,--no-sidecar,split:config precedence, and the QuickSight semantic layout. - Update the README quick-start example/output tree and link to the configuration guide.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| README.md | Updates the quick-start tree output to reflect the QuickSight preset’s semantic layout and links to the config guide. |
| docs/guides/configuring-for-yaml-types.md | Documents presets (incl. semantic rules), --no-sidecar, and updated QuickSight worked examples. |
| docs/adr/0002-preset-semantic-explosion.md | Introduces ADR-0002 capturing the preset-based semantic explosion design and key invariants. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Final slice of preset-based semantic explosion (#17) — docs only. Records the design shipped across #14–#16 and updates the user-facing docs to match the actual behavior.
Changes
docs/adr/0002-preset-semantic-explosion.md): the preset/rule-engine architecture — presets supersede profiles (carrying option defaults + path-anchored rules); theForceExtractandSidecaractions; the local per-scalar fidelity guard and the two yaml.v3 invariants its soundness rests on (content-only style, disabled wrapping — with the "don't addSetWidth" warning); thesplit:config precedence; andverifyrunning the real preset. Marked as superseding ADR-0001 §4'sprofile. Lists deferred items (user-definable rules, more sidecars, nested identity paths).--preset(+ deprecated--profile),--no-sidecar, thesplit:config block, and the QuickSight semantic layout — sheets → folders, subcomponent categories → files, dataset SQL →.sqlsidecars. Fixes the now-stale "visuals stay inline at depth 3" claim (the preset now folders them via rules).Verification
split --preset quicksightoutput (.../sheets/customer-analysis/{visuals,filtercontrols,...}.yml).go build ./...clean (docs-only change).--profileas primary, "four flags", "visuals inline") outside the historical ADR-0001 record.Closes #17.
🤖 Generated with Claude Code