feat: add recce-docs-guide local skill and update CLAUDE.md #94
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| <figure markdown> | ||
| {: .shadow} | ||
| <figcaption>Description of what the image shows</figcaption> | ||
| </figure> | ||
| ``` | ||
|
|
||
| For top-level pages (e.g., `docs/index.md`): | ||
|
|
||
| ```markdown | ||
| <figure markdown> | ||
| {: .shadow} | ||
| <figcaption>Description of what the image shows</figcaption> | ||
| </figure> | ||
| ``` | ||
|
|
||
| - 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` | ||
|
Contributor
There was a problem hiding this comment. Why do we need this here? It feel duplicated with https://github.com/DataRecce/recce-team/blob/main/recce-team/context/product/terminology.md and https://github.com/DataRecce/recce-team/blob/main/recce-team/context/product/recce-context.md |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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): | ||
| ``` | ||
| <figure markdown> | ||
| {: .shadow} | ||
| <figcaption>Description</figcaption> | ||
| </figure> | ||
| ``` | ||
| - 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 |
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
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
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
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
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.
Uh oh!
There was an error while loading. Please reload this page.