diff --git a/.claude/skills/recce-docs-guide.md b/.claude/skills/recce-docs-guide.md new file mode 100644 index 00000000..7a55d97f --- /dev/null +++ b/.claude/skills/recce-docs-guide.md @@ -0,0 +1,188 @@ +--- +name: recce-docs-guide +description: > + Use when writing, editing, or reviewing any documentation in this repo. + Triggers on any work touching files under docs/, mkdocs.yml, or claude/. + Handles MkDocs conventions, page structure, and formatting standards. + Delegates voice, terminology, QA, and AISEO to the recce-team plugin. +--- + +# Recce Docs Guide + +## Pre-flight: plugin check + +Before any work, verify the `recce-team` plugin is available by checking if the `recce-team:writing-content` skill exists. + +If the plugin is NOT installed, stop and show: + +> The `recce-team` plugin is required for writing principles, terminology, QA, and AISEO reviews. +> +> Install it: +> ``` +> claude plugin add https://github.com/DataRecce/recce-team +> ``` +> +> Then retry your request. + +Do not proceed without the plugin. + +## Scope detection + +Assess the scope of the documentation work to choose the right workflow: + +**Lightweight path** — use when: +- Editing 1-2 existing pages +- No new pages created +- No navigation changes in `mkdocs.yml` + +**Full path** — use when: +- Creating new pages +- Changing `mkdocs.yml` navigation +- Touching 3+ pages +- Restructuring or consolidating content + +The user can override: request full workflow on a small edit, or lightweight on a large one. + +## Lightweight path + +1. Read local docs-specific context: + - `claude/writing-principles.md` — ICP definitions, audience strategy, tone variants + - `claude/terminology.md` — confusion risks, conflicting usage, clarification patterns +2. Invoke `recce-team:writing-content` for voice and formatting checks +3. Apply the MkDocs conventions below +4. Done — no QA/AISEO required + +## Full path + +1. Read local docs-specific context: + - `claude/writing-principles.md` — ICP definitions, audience strategy, tone variants + - `claude/terminology.md` — confusion risks, conflicting usage, clarification patterns + - `claude/KNOWLEDGE_BASE.md` — site map / section index +2. Delegate to `recce-team:writing-content` which handles: + - Planning (action types, doc types, source materials) + - Structure approval + - Drafting content under `docs/` in the appropriate section + - QA review (`/recce-team:qa`) + - AISEO review (`/recce-team:aiseo-review`) +3. Apply MkDocs conventions below on top of the drafted content +4. Handle nav updates and redirects in `mkdocs.yml` + +## MkDocs conventions + +### Page structure template + +Every documentation page should follow this structure: + +```markdown +--- +title: [Descriptive Title] +--- + +# [H1 Title - Title Case, matches page title] + +[Brief introduction — what this page covers and why it matters] + +## [Value-first conceptual overview] +[Explain the concept, especially why and what value it provides, before implementation] + +## [Step-by-step guide] +[Numbered steps with code examples or screenshots] + +## [Common scenarios/use cases] +[Real-world applications and variations] + +## [Troubleshooting] (if applicable) +[Common issues and solutions] + +## [What's next] +[Links to related topics and logical next steps] +``` + +### Heading capitalization + +- **Page title (H1):** Title Case — capitalize every word +- **H2 and below:** Sentence case — only capitalize the first word + +### Image format + +Use the standardized figure format with shadow styling. The image path is relative to the current page location: + +For pages in subdirectories (e.g., `docs/setup-guides/connect-git.md`): + +```markdown +
+ ![Alt text](../assets/images/section/filename.gif){: .shadow} +
Description of what the image shows
+
+``` + +For top-level pages (e.g., `docs/index.md`): + +```markdown +
+ ![Alt text](assets/images/section/filename.gif){: .shadow} +
Description of what the image shows
+
+``` + +- Use consistent naming: `section-feature-description.png` +- Include meaningful alt text +- Keep screenshots current + +### Admonitions + +Use MkDocs Material admonition syntax: + +```markdown +!!! tip + Use for helpful suggestions and best practices + +!!! note + Use for important information and context + +!!! warning + Use for potential issues or important caveats + +!!! info + Use for additional context or background information +``` + +### Code blocks + +- Use `shell` for commands +- Show expected output when helpful +- Use `diff` for configuration changes + +```shell +pip install recce +recce server +``` + +```diff + existing_line +- removed_line ++ added_line +``` + +### Bold usage + +Use bold sparingly. Too many highlights lose focus and make content harder to read. + +### Navigation updates + +When adding or moving pages: +1. Update `mkdocs.yml` nav section +2. Add redirects under `plugins > redirects > redirect_maps` for moved/deleted pages: + +```yaml +plugins: + - redirects: + redirect_maps: + 'old-path/file.md': 'new-path/file.md' +``` + +### File and path conventions + +- Use `./` for relative paths: `./models/staging/stg_payments.sql` +- Highlight important files with code formatting: `profiles.yml`, `dbt_project.yml` +- Use consistent file extensions: `.sql`, `.yml`, `.md` diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..23db771c --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,64 @@ +This is a documentation repository for Recce, a Data Review Agent for dbt data validation. All content follows strict writing and terminology standards. + +## Writing rules for PR review + +When reviewing pull requests that modify files under `docs/`, `mkdocs.yml`, or `claude/`, apply these rules: + +### Terminology + +- Use "Recce" (capitalized), never "recce" +- Use "dbt" (lowercase), never "DBT" +- Use "data validation" not "data testing" +- Use "release changes" not "deploy changes" +- Use "development stage" not "environment" when referring to dev/prod +- Use "warehouse connection" not "database connection" +- Use "run dbt" not "execute dbt" or "build models" +- Use "data changes" not "code changes" when referring to what users validate +- Use "validation checks" not "unit tests" +- Use "change review" not "code review" +- Feature names are capitalized: Row Count Diff, Schema Diff, Profile Diff, Value Diff, Top-K Diff, Histogram Diff, Lineage Diff, Column-Level Lineage (CLL) +- Generic concepts are lowercase: "data diffing", "impact analysis" +- Use "PR" not "Pull Request" (unless specifically about GitLab) +- Spell out acronyms on first use: "Column-Level Lineage (CLL)" + +### Voice + +- Omit needless words: cut filler phrases ("the fact that", "in order to") +- Use active voice: "Recce validates" not "validation is performed by Recce" +- Be specific: use concrete numbers, exact tool names +- Confident tone: "Here's how to set up validation" not "You might want to try this approach" +- No false humility ("just", "only", "merely") or overselling ("amazing", "incredible") +- Aim for sentences under 20 words + +### MkDocs formatting + +- Page title (H1): Title Case +- H2 and below: Sentence case (only capitalize first word) +- Images must use the figure format with shadow styling. Path is relative to the page location (`../assets/images/` for subdirectory pages, `assets/images/` for top-level pages): + ``` +
+ ![Alt text](../assets/images/section/filename.gif){: .shadow} +
Description
+
+ ``` +- Use MkDocs Material admonitions: `!!! tip`, `!!! note`, `!!! warning`, `!!! info` +- Use `shell` for command code blocks +- Use `diff` for showing configuration changes +- Use bold sparingly: too many highlights lose focus +- Add line breaks between sentences and lists for proper rendering + +### Content strategy + +- Cloud-first: present Recce Cloud as primary, OSS as alternative +- Lead with value: explain why before how +- Single source of truth: state details once, reference elsewhere +- When moving or deleting pages, verify redirects are added in `mkdocs.yml` + +### Common review flags + +- "environment" used where "development stage" or "dbt target" would be clearer for data teams +- "deploy" used where "release" would be more appropriate for data workflows +- "testing" used where "validation" is the preferred Recce term +- Heading capitalization inconsistency (Title Case vs sentence case) +- Missing alt text on images +- Duplicated information that should be stated once and referenced diff --git a/.gitignore b/.gitignore index 5b865f47..8f047fab 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,8 @@ site/ node_modules/ .cache/ .nvmrc +.claude/superpowers/ +.claude/settings.local.json # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839 diff --git a/CLAUDE.md b/CLAUDE.md index bf2b80e4..c721071b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,12 +27,17 @@ mkdocs build # Build static site to /site | Path | Purpose | |------|---------| -| `docs/` | Markdown source files (numbered sections) | +| `docs/` | Markdown source files | | `mkdocs.yml` | Site config and nav structure | -| `claude/` | Writing principles and terminology guides | +| `claude/` | Docs-specific writing principles, terminology, and site map | +| `.claude/skills/` | Local Claude Code skills (docs guide) | | `docs/assets/images/` | Screenshots and diagrams | | `site/` | Built output (git-ignored) | -## Knowledge Base +## Plugin Dependency -→ `claude/KNOWLEDGE_BASE.md` +Voice, formatting, QA, and AISEO reviews are provided by the `recce-team` plugin. Install it: + +``` +claude plugin add https://github.com/DataRecce/recce-team +``` diff --git a/docs/setup-guides/claude-plugin.md b/docs/setup-guides/claude-plugin.md index a6538331..9b24835b 100644 --- a/docs/setup-guides/claude-plugin.md +++ b/docs/setup-guides/claude-plugin.md @@ -86,7 +86,7 @@ This walks you through: When setup completes, you'll see confirmation that the MCP server is running and connected. -Once connected, Claude has access to the full set of Recce validation tools, including Lineage Diff, Column-Level Lineage, row-level Value Diff, Top-K Diff, Histogram Diff, and more. Try asking questions about your data changes: +Once connected, Claude has access to all Recce validation tools: Lineage Diff, Column-Level Lineage, Value Diff, Top-K Diff, Histogram Diff, and more. Try asking about your data changes: ``` You: What schema changes happened in my current branch? @@ -203,7 +203,7 @@ Recce works with any dbt adapter, including Snowflake, BigQuery, Redshift, Datab Yes. The plugin works with the open source version for local validation. [Cloud](https://cloud.reccehq.com/) adds automated PR review, team collaboration, and persistent validation history. -## Next Steps +## Next steps - [Recce MCP Server](mcp-server.md): full tool reference, agent workflow guide, and configuration for Cursor, Windsurf, and other AI agents - [Column-Level Lineage](../what-you-can-explore/column-level-lineage.md): understand how column changes propagate through your models diff --git a/docs/setup-guides/mcp-server.md b/docs/setup-guides/mcp-server.md index eed936de..b44baa9e 100644 --- a/docs/setup-guides/mcp-server.md +++ b/docs/setup-guides/mcp-server.md @@ -60,7 +60,7 @@ dbt docs generate --target-path target-base This creates `target-base/manifest.json` and `target-base/catalog.json`. The MCP server compares these two artifact sets to produce diffs. !!! note - If `target-base/` is missing, the MCP server starts in **single-environment mode** — all tools remain available, but diff results show no changes because both sides reference the same data. Generate base artifacts to enable real comparisons. + If `target-base/` is missing, the MCP server starts in **single-source mode** — all tools remain available, but diff results show no changes because both sides reference the same data. Generate base artifacts to enable real comparisons. ## Installation @@ -197,7 +197,7 @@ Choose the tab for your AI agent. **stdio** is simpler (no separate process to m ## Available tools -The MCP server exposes these tools to your AI agent. Tools are grouped by availability — some work in all modes, while diff tools require a running server with warehouse access. +The MCP server exposes these tools to your AI agent. Tools are grouped by function: metadata tools work with dbt artifacts only, while diff tools require a warehouse connection. ### Metadata and lineage tools @@ -239,9 +239,6 @@ These tools manage validation checks stored in the running Recce server instance Checks can also be configured as preset checks in `recce.yml`. See [Preset checks](../collaboration/preset-checks.md) for details. -!!! note - If base artifacts (`target-base/`) are not present, the server starts in **single-environment mode** — all tools remain available, but diff results show no changes. Generate base artifacts to enable real comparisons. - ## How agents use these tools The metadata and diff tools work together in a structured validation workflow. A well-configured AI agent follows this pattern: @@ -341,7 +338,7 @@ No. The MCP server is part of Recce OSS and free to use. [Recce Cloud](https://c [MCP (Model Context Protocol)](https://modelcontextprotocol.io) is an open standard that allows AI agents to call external tools. Recce implements an MCP server so AI agents can run data diffs against your warehouse on demand. -## Next Steps +## Next steps - [Recce Claude Plugin](claude-plugin.md): guided setup for Claude Code users with interactive commands - [Column-Level Lineage](../what-you-can-explore/column-level-lineage.md): trace how column changes propagate through your model graph