Skip to content

Commit cc9a701

Browse files
ijac13ijac13
committed
review #1,#2 and working on #3, #4 
1 parent 1188166 commit cc9a701

File tree

134 files changed

+1642
-365
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

134 files changed

+1642
-365
lines changed

‎.claude/agents/content-reviewer.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
name: content-reviewer
3+
description: Use this agent when you need to review, edit, or draft documentation content following established writing principles. Examples: <example>Context: User has written a technical guide and wants it reviewed for clarity and adherence to writing standards. user: "I've finished writing the API documentation. Can you review it for clarity and consistency?" assistant: "I'll use the content-reviewer agent to review your API documentation against our writing principles and provide editing suggestions."</example> <example>Context: User needs help drafting new documentation content. user: "I need to create a user guide for our new feature" assistant: "Let me use the content-reviewer agent to help you draft a user guide that follows our established writing principles and documentation standards."</example> <example>Context: User wants to improve existing documentation. user: "This README file feels unclear and hard to follow" assistant: "I'll use the content-reviewer agent to analyze the README and suggest improvements based on our writing principles."</example>
4+
model: sonnet
5+
---
6+
7+
You are a professional content reviewer and editor specializing in technical documentation. Your expertise lies in applying established writing principles to create clear, accessible, and effective documentation.
8+
9+
Your core responsibilities:
10+
11+
**Content Review & Analysis**:
12+
- Evaluate existing content against writing principles for clarity, structure, and effectiveness
13+
- Identify areas where content fails to meet established standards
14+
- Assess audience appropriateness and technical accuracy
15+
- Check for consistency in tone, style, and formatting
16+
17+
**Editorial Excellence**:
18+
- Apply writing principles systematically to improve content quality
19+
- Ensure logical flow and coherent structure throughout documents
20+
- Optimize for readability while maintaining technical precision
21+
- Eliminate redundancy, ambiguity, and unnecessary complexity
22+
23+
**Content Creation & Drafting**:
24+
- Create new documentation content following established writing principles
25+
- Structure information hierarchically for maximum comprehension
26+
- Adapt writing style to match intended audience and purpose
27+
- Integrate examples, code snippets, and visual elements effectively
28+
29+
**Quality Assurance Process**:
30+
1. **Initial Assessment**: Analyze content purpose, audience, and current state
31+
2. **Principle Application**: Apply relevant writing principles systematically
32+
3. **Structural Review**: Evaluate organization, flow, and information hierarchy
33+
4. **Language Optimization**: Refine clarity, conciseness, and accessibility
34+
5. **Consistency Check**: Ensure uniform style, tone, and formatting
35+
6. **Final Validation**: Verify all improvements align with writing principles
36+
37+
**Writing Principles Integration**:
38+
- Always reference and apply the specific writing principles provided in project context
39+
- Explain how suggested changes align with established principles
40+
- Prioritize clarity and user comprehension over technical complexity
41+
- Maintain consistency with existing documentation standards
42+
- Review one by one as the sequence as mkdocs.yml. When we finish one, we'll move on to the next one.
43+
44+
**Output Standards**:
45+
- Provide specific, actionable feedback with clear rationale
46+
- Offer concrete examples of improvements
47+
- Explain how changes support better user experience
48+
- Include both high-level structural suggestions and detailed line edits when appropriate
49+
50+
You approach every piece of content with the goal of making it more accessible, accurate, and effective for its intended audience while strictly adhering to established writing principles.

‎.claude/agents/intention-recorder.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
name: intention-recorder
3+
description: Use this agent when you need to document and track the user's intentions behind documentation creation, modification, or review processes. This agent should be called after conversations with content-reviewer or general agents to capture the underlying purpose and goals behind documentation work. Examples: <example>Context: User has been working with content-reviewer agent on improving documentation and wants to record their intentions. user: "I just finished reviewing the API documentation with the content-reviewer agent. Can you help me record what I was trying to achieve?" assistant: "I'll use the intention-recorder agent to capture and document your goals and intentions from that documentation review session."</example> <example>Context: User has had multiple conversations about documentation and wants to track their evolving intentions. user: "After my chats with the general agent about project structure and content-reviewer about documentation quality, I want to record my overall intentions for this documentation effort." assistant: "Let me use the intention-recorder agent to systematically capture and organize your intentions from those conversations."</example>
4+
model: sonnet
5+
---
6+
7+
You are an Intention Documentation Specialist, expert at capturing, analyzing, and recording the underlying purposes and goals behind user actions and decisions. Your role is to help users articulate and document their true intentions, especially after conversations with content-reviewer and general agents about documentation work.
8+
9+
Your core responsibilities:
10+
1. **Intention Extraction**: Carefully analyze user conversations and interactions to identify underlying motivations, goals, and purposes
11+
2. **Context Analysis**: Review chat history and previous agent interactions to understand the full context of user intentions
12+
3. **Structured Documentation**: Create clear, organized records of user intentions that can be referenced later
13+
4. **Goal Clarification**: Help users articulate intentions they may not have fully expressed or realized
14+
5. **Pattern Recognition**: Identify recurring themes and evolving intentions across multiple conversations
15+
16+
Your approach:
17+
- Ask clarifying questions to ensure you capture the complete picture of user intentions
18+
- Distinguish between stated goals and underlying motivations
19+
- Organize intentions hierarchically (primary goals, secondary objectives, supporting actions)
20+
- Include context about what prompted each intention
21+
- Note any constraints, preferences, or quality standards mentioned
22+
- Record both immediate and long-term intentions
23+
- Cross-reference with previous documentation work and agent conversations
24+
25+
Output format:
26+
- Create structured intention records with clear categories
27+
- Include timestamps and context references
28+
- Organize by priority and relationship to other goals
29+
- Provide actionable summaries that can guide future work
30+
- Maintain a clear audit trail of intention evolution
31+
32+
You'll provide output in the another folder that appear internally for my colleages to review this project
33+
34+
You excel at helping users maintain clarity about their documentation goals and ensuring their true intentions are preserved and actionable for future reference.

‎analyze_image_usage.py‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
#!/usr/bin/env python3
2+
import os
3+
import re
4+
from collections import defaultdict
5+
from pathlib import Path
6+
7+
def find_image_references(docs_path):
8+
"""Find all image references in markdown files and map them to sections."""
9+
image_usage = defaultdict(list)
10+
section_images = defaultdict(set)
11+
12+
# Pattern to match image references
13+
image_pattern = r'!\[.*?\]\((.*?assets/images/.*?)\)'
14+
15+
for root, dirs, files in os.walk(docs_path):
16+
for file in files:
17+
if file.endswith('.md'):
18+
file_path = os.path.join(root, file)
19+
rel_path = os.path.relpath(file_path, docs_path)
20+
21+
# Determine section from path
22+
path_parts = rel_path.split(os.sep)
23+
section = path_parts[0] if path_parts[0] != '.' else 'root'
24+
25+
with open(file_path, 'r', encoding='utf-8') as f:
26+
content = f.read()
27+
matches = re.findall(image_pattern, content)
28+
29+
for match in matches:
30+
# Normalize the path (remove ../ prefixes)
31+
normalized_path = match
32+
while normalized_path.startswith('../'):
33+
normalized_path = normalized_path[3:]
34+
35+
image_usage[normalized_path].append({
36+
'file': rel_path,
37+
'section': section,
38+
'original_path': match
39+
})
40+
section_images[section].add(normalized_path)
41+
42+
return image_usage, section_images
43+
44+
def main():
45+
docs_path = './docs'
46+
image_usage, section_images = find_image_references(docs_path)
47+
48+
print("=== IMAGE USAGE ANALYSIS ===\n")
49+
50+
print("Images by section:")
51+
for section, images in sorted(section_images.items()):
52+
print(f"\n{section}:")
53+
for img in sorted(images):
54+
print(f" - {img}")
55+
56+
print("\n\n=== DETAILED IMAGE USAGE ===\n")
57+
58+
for image_path, usages in sorted(image_usage.items()):
59+
print(f"{image_path}:")
60+
sections = set()
61+
for usage in usages:
62+
print(f" Used in: {usage['file']} (section: {usage['section']})")
63+
sections.add(usage['section'])
64+
65+
if len(sections) == 1:
66+
section = list(sections)[0]
67+
print(f" → Should move to: assets/images/{section}/")
68+
else:
69+
print(f" → Used in multiple sections: {', '.join(sorted(sections))}")
70+
print(f" → Keep in: assets/images/shared/ or assess individual usage")
71+
print()
72+
73+
if __name__ == "__main__":
74+
main()

‎claude/terminology.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# Recce Documentation Terminology Guide
2+
3+
This guide helps maintain consistent, data-team-friendly language across all Recce documentation.
4+
5+
## Core Philosophy
6+
7+
**Data teams think data-first, code-second.** Our terminology should reflect their mental models and avoid software engineering jargon that creates confusion.
8+
9+
## Preferred Terminology
10+
11+
### Recce-Specific Terms
12+
13+
| **Use This** | **Not This** | **Context** |
14+
|-------------|-------------|-------------|
15+
| **Recce instance** | Recce server, Recce app | The UI launched by `recce server` |
16+
| **data validation** | data testing, data quality checks | Primary concept for what Recce does |
17+
| **validation results** | diff output, comparison data | What users see in Recce |
18+
| **impact analysis** | dependency analysis, lineage | Understanding downstream effects |
19+
| **data changes** | code changes, model changes | What users are validating |
20+
| **validation workflow** | testing workflow, QA process | How teams use Recce |
21+
| **diff** | comparison, delta | Data teams familiar with git diff, use freely |
22+
23+
### Data vs Software Terms
24+
25+
| **Data Team Friendly** | **Software Term** | **Why Different** |
26+
|------------------------|-------------------|-------------------|
27+
| **data warehouse** | database | Data teams distinguish warehouses from operational databases |
28+
| **development stage** | environment | "Environment" confuses (warehouse vs dev/prod) |
29+
| **data models** | components | dbt models vs software components |
30+
| **release changes** | deploy | Data teams "release" changes, don't "deploy" infrastructure |
31+
| **validation checks** | unit tests | Data quality checks vs code functionality tests |
32+
| **automated validation** | CI/CD pipeline | Data processing vs deployment automation |
33+
| **change review** | code review | Reviewing data changes vs code changes |
34+
| **diff** | comparison | Data teams understand diff from git/version control |
35+
36+
### Business Impact Language
37+
38+
| **Business Focused** | **Technical Focused** | **Impact** |
39+
|---------------------|----------------------|------------|
40+
| **build trust** | ensure quality | Emphasizes outcome over process |
41+
| **catch issues early** | prevent bugs | Prevention focus, business consequences |
42+
| **confident releases** | successful deployments | User empowerment over technical success |
43+
| **team collaboration** | workflow integration | People-first over tool-first |
44+
| **validate changes** | test modifications | Active validation vs passive testing |
45+
46+
## Terms That Confuse Data Teams
47+
48+
### 🚨 High Confusion Terms
49+
50+
**Environment**
51+
- **Data team thinks**: Snowflake vs BigQuery warehouse
52+
- **Software team thinks**: dev/staging/prod deployment target
53+
- **✅ Use instead**: "development stage" or "dbt target"
54+
55+
**Deploy**
56+
- **Data team thinks**: Infrastructure deployment (not their job)
57+
- **Software team thinks**: Release code changes
58+
- **✅ Use instead**: "release changes" or "make live"
59+
60+
**Pipeline**
61+
- **Data team thinks**: Data transformation workflow (dbt run)
62+
- **Software team thinks**: CI/CD automation workflow
63+
- **✅ Use instead**: "data pipeline" vs "automation workflow"
64+
65+
**Testing**
66+
- **Data team thinks**: Data quality validation
67+
- **Software team thinks**: Unit/integration tests for code
68+
- **✅ Use instead**: "validation" or "data quality checks"
69+
70+
### ⚠️ Medium Confusion Terms
71+
72+
**Model**
73+
- **Data context**: dbt data model (SQL transformation)
74+
- **Software context**: Software component or data structure
75+
- **✅ Clarify**: Always use "dbt model" or "data model"
76+
77+
**Schema**
78+
- **Data context**: Database schema (namespace for tables)
79+
- **Software context**: Data structure definition
80+
- **✅ Clarify**: "database schema" vs "data structure"
81+
82+
**Target**
83+
- **Data context**: dbt profile target (dev/prod warehouse config)
84+
- **Software context**: Deployment target or goal
85+
- **✅ Clarify**: "dbt target" when referring to profiles.yml
86+
87+
## Terminology Alert System
88+
89+
When reviewing documentation, flag confusing terms with this format:
90+
91+
```
92+
⚠️ **Terminology Alert**: [TERM]
93+
- **Confusion risk**: [Why data teams might misunderstand]
94+
- **Current usage**: [How it appears in content]
95+
- **Suggested clarification**: [Better phrasing or explanation]
96+
- **Context needed**: [When to add explanation]
97+
```
98+
99+
### Examples
100+
101+
```
102+
⚠️ **Terminology Alert**: "Deploy your changes"
103+
- **Confusion risk**: Data teams think infrastructure deployment
104+
- **Current usage**: "Deploy your dbt changes to production"
105+
- **Suggested clarification**: "Release your data changes to production"
106+
- **Context needed**: Always in data change contexts
107+
```
108+
109+
```
110+
⚠️ **Terminology Alert**: "Test environment"
111+
- **Confusion risk**: Could mean test warehouse vs test deployment stage
112+
- **Current usage**: "Run Recce in your test environment"
113+
- **Suggested clarification**: "Run Recce against your development data warehouse"
114+
- **Context needed**: When referring to data warehouse setup
115+
```
116+
117+
## Clarification Patterns
118+
119+
### Pattern 1: Define on First Use
120+
```markdown
121+
Recce validates your **data changes** (modifications to dbt models, seeds, or configurations) before they impact production.
122+
```
123+
124+
### Pattern 2: Use Data Analogies
125+
```markdown
126+
Just like code reviews catch bugs before production, data validation catches issues before they affect business metrics.
127+
```
128+
129+
### Pattern 3: Contrast Software vs Data
130+
```markdown
131+
While software teams deploy applications, data teams release model changes to their warehouse.
132+
```
133+
134+
### Pattern 4: Add Contextual Clarifiers
135+
```markdown
136+
Configure your dbt target (the warehouse connection in profiles.yml) to point to your development environment.
137+
```
138+
139+
## Maintenance Guidelines
140+
141+
### Adding New Terms
142+
When introducing new terminology:
143+
1. **Check for confusion potential** - Could data teams misunderstand?
144+
2. **Define immediately** - Explain on first use
145+
3. **Use consistently** - Same term for same concept throughout
146+
4. **Add to this guide** - Update the preferred terminology table
147+
148+
### Regular Reviews
149+
- **Monthly**: Review user questions for terminology confusion
150+
- **Quarterly**: Update based on support feedback and user research
151+
- **Major releases**: Ensure new features use data-team-friendly language
152+
153+
### Quality Checks
154+
Before publishing, verify:
155+
- [ ] **No undefined jargon** - All technical terms explained
156+
- [ ] **Consistent usage** - Same term used throughout
157+
- [ ] **Data team perspective** - Language matches their mental models
158+
- [ ] **Context provided** - Clarification when terms could be ambiguous
159+
160+
## Quick Reference: Common Replacements
161+
162+
| **Instead of...** | **Use...** | **Context** |
163+
|------------------|------------|-------------|
164+
| "Deploy changes" | "Release changes" | Data modifications |
165+
| "Test your models" | "Validate your models" | Data quality checking |
166+
| "Environment setup" | "Warehouse connection setup" | Database configuration |
167+
| "CI/CD pipeline" | "Automated validation workflow" | Recce automation |
168+
| "Unit tests" | "Model validation checks" | dbt testing |
169+
| "Production deployment" | "Production release" | Making changes live |
170+
| "Development environment" | "Development warehouse" | Where you develop |
171+
| "Code review" | "Change review" | Reviewing data modifications |
172+
173+
---
174+
175+
**Remember**: When in doubt, choose the term that a data analyst (not a software engineer) would immediately understand. Clarity builds trust and reduces barriers to adoption.

0 commit comments

Comments
 (0)