trent_larson/daily-notification-plugin
4
0
Fork 0
Code Issues Pull Requests 2 Projects Releases Wiki Activity

refactor(cursor-rules): restructure rules organization and enhance documentation standards

Browse Source 
- Reorganize cursor rules into logical directories (app/, docs/, features/, etc.)
- Move project.mdc to app/ directory for better organization
- Enhance documentation.mdc with base_context.mdc principles and markdown standards
- Improve time.mdc with comprehensive time handling guidelines
- Remove outdated/unused rule files (general_development, logging, progress_reports, version_control, versioning)
- Establish new documentation standards emphasizing human competence and collaboration
- Ensure all documentation follows markdown.mdc linting rules

This restructuring improves rule discoverability and establishes consistent documentation
standards across the project while maintaining the human competence first approach.
This commit is contained in:
Matthew Raymer
2025-08-17 12:21:06 +00:00
parent bddc1cfebf
commit 0eb709aaf0
24 changed files with 2321 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

345
.cursor/rules/docs/documentation.mdc Normal file
View File

@@ -0,0 +1,345 @@
# Documentation Generation — Human Competence First
**Author**: Matthew Raymer
**Date**: 2025-08-17
**Status**: 🎯 **ACTIVE** - Core Documentation Standards
## Overview
This guide establishes **how documentation should be created and maintained**
across all projects, emphasizing **human competence building** and
**collaborative learning** while ensuring technical accuracy and maintainability.
## Core Principles (Human Competence First)
### 1. **Learning Over Information Dumping**
- **Educational value**: Documents must clearly explain system workings
- **Progressive complexity**: Start simple, build to advanced concepts
- **Real-world examples**: Include practical, actionable examples
- **Why it matters**: Understanding the "why" builds deeper competence
### 2. **Collaboration Over Isolation**
- **Team review**: Documentation should invite discussion and iteration
- **Shared ownership**: Multiple perspectives improve quality and accuracy
- **Feedback loops**: Regular review cycles keep content relevant
- **Why it matters**: Collaborative documentation builds team knowledge
### 3. **Maintainability Over Completeness**
- **Small, focused sets**: Prefer depth over breadth
- **Worth preserving**: Content must motivate humans to keep it updated
- **Clear ownership**: Designate maintainers for each document
- **Why it matters**: Maintainable docs stay useful over time
### 4. **Quality Over Quantity**
- **Avoid filler**: No shallow, generic, or AI-generated explanations
- **Clarity first**: Complex concepts explained simply
- **Actionable content**: Readers should know what to do next
- **Why it matters**: Quality content builds trust and competence
## Documentation Standards
### Content Structure
#### Document Header (Required)
```markdown
# Document Title
**Author**: [Name]
**Date**: YYYY-MM-DD
**Status**: 🎯 **STATUS** - Brief description
**Maintainer**: [Name]
## Overview
Brief description of the document's purpose and scope.
```
#### Section Organization
1. **Overview/Introduction** - Purpose and scope
2. **Current State** - What exists now
3. **Implementation Details** - How things work
4. **Examples** - Real-world usage
5. **Next Steps** - What to do next
6. **References** - Related resources
### Writing Guidelines
#### **For LLMs (Required)**
- **Always start with purpose**: Why does this document exist?
- **Include learning objectives**: What will readers understand after reading?
- **Provide examples**: Show, don't just tell
- **End with action**: What should readers do next?
#### **For Human Writers**
- **Write for your future self**: Will you understand this in 6 months?
- **Consider skill levels**: Different readers have different needs
- **Include context**: Why does this matter for the project?
- **Invite feedback**: How can this be improved?
## Documentation Types
### 1. **Technical Guides**
- **Purpose**: Explain how systems work
- **Audience**: Developers, engineers, technical users
- **Focus**: Implementation details, APIs, configurations
- **Examples**: Code snippets, configuration files, diagrams
### 2. **Process Documentation**
- **Purpose**: Explain how to accomplish tasks
- **Audience**: Team members, stakeholders
- **Focus**: Step-by-step procedures, workflows
- **Examples**: Checklists, flowcharts, decision trees
### 3. **Architecture Documents**
- **Purpose**: Explain system design and structure
- **Audience**: Architects, developers, stakeholders
- **Focus**: High-level design, trade-offs, decisions
- **Examples**: System diagrams, ADRs, design patterns
### 4. **User Guides**
- **Purpose**: Help users accomplish goals
- **Audience**: End users, customers
- **Focus**: User workflows, features, troubleshooting
- **Examples**: Screenshots, step-by-step instructions
## Quality Assurance
### **Before Publishing Documentation**
- [ ] **Purpose clear**: Why does this document exist?
- [ ] **Audience defined**: Who is this written for?
- [ ] **Examples included**: Are there practical examples?
- [ ] **Actionable**: Do readers know what to do next?
- [ ] **Maintainable**: Is it easy to keep updated?
- [ ] **Collaborative**: Does it invite team input?
### **After Publishing Documentation**
- [ ] **Feedback collected**: Have team members reviewed it?
- [ ] **Usage tracked**: Are people actually using it?
- [ ] **Updates planned**: When will it be reviewed next?
- [ ] **Ownership clear**: Who maintains this document?
## Implementation Examples
### Good Documentation Example
```markdown
# User Authentication System
**Author**: Matthew Raymer
**Date**: 2025-08-17
**Status**: 🎯 **ACTIVE** - Production System
**Maintainer**: Security Team
## Overview
This document explains how user authentication works in our system,
including login flows, security measures, and troubleshooting steps.
## Learning Objectives
After reading this document, you will understand:
- How users log in and authenticate
- What security measures protect user accounts
- How to troubleshoot common authentication issues
- When to escalate security concerns
## Current Implementation
### Login Flow
1. User enters credentials
2. System validates against database
3. JWT token generated and returned
4. Token stored in secure cookie
### Security Measures
- Password hashing with bcrypt
- Rate limiting on login attempts
- JWT expiration after 24 hours
- HTTPS enforcement for all auth requests
## Examples
### Login Request
```json
POST /api/auth/login
{
"email": "user@example.com",
"password": "securepassword123"
}
```
### Successful Response
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires": "2025-08-18T12:00:00Z"
}
```
## Troubleshooting
### Common Issues
- **Invalid credentials**: Check email/password combination
- **Token expired**: User needs to log in again
- **Rate limited**: Wait 15 minutes before retrying
### Escalation Path
1. Check system logs for errors
2. Verify database connectivity
3. Contact security team if suspicious activity
## Next Steps
1. **Test the system**: Try logging in with test credentials
2. **Review security**: Ensure your implementation follows these patterns
3. **Document issues**: Add new troubleshooting steps as you discover them
## References
- [JWT Documentation](https://jwt.io/)
- [Security Best Practices](./security-guide.md)
- [API Reference](./api-docs.md)
---
**Last Updated**: 2025-08-17
**Next Review**: 2025-09-17
**Stakeholders**: Development Team, Security Team, Product Team
### Bad Documentation Example
```markdown
# Authentication
This document describes the authentication system.
## Overview
The system has authentication.
## Implementation
Users can log in.
## Conclusion
That's how authentication works.
```
## Collaboration Points
### **Code Reviews**
- Include documentation updates in code review process
- Ensure new features have corresponding documentation
- Validate that examples match actual implementation
### **Team Reviews**
- Schedule regular documentation review sessions
- Invite different team members to review content
- Collect feedback on clarity and usefulness
### **User Testing**
- Have actual users try to follow documentation
- Observe where they get stuck or confused
- Update content based on real usage patterns
## Maintenance Schedule
### **Weekly**
- Review documentation usage metrics
- Collect feedback from team members
- Plan updates for outdated content
### **Monthly**
- Full review of high-priority documents
- Update examples and screenshots
- Validate links and references
### **Quarterly**
- Comprehensive review of all documentation
- Identify gaps and opportunities
- Plan major documentation projects
## Success Metrics
### **Usage Metrics**
- **Document views**: How often is content accessed?
- **Time on page**: How long do readers spend?
- **Search queries**: What are people looking for?
### **Quality Metrics**
- **Feedback scores**: How do readers rate content?
- **Update frequency**: How often is content refreshed?
- **Maintainer satisfaction**: Are maintainers happy with their docs?
### **Competence Metrics**
- **Question reduction**: Fewer basic questions from team?
- **Implementation speed**: Faster feature development?
- **Knowledge transfer**: Better onboarding for new team members?
## Tools and Resources
### **Documentation Platforms**
- **Markdown**: Standard format for technical documentation
- **GitBook**: Collaborative documentation hosting
- **Notion**: Team knowledge management
- **Confluence**: Enterprise documentation platform
### **Quality Tools**
- **Markdown linting**: Ensure consistent formatting
- **Link checking**: Validate references and links
- **Spell checking**: Maintain professional appearance
- **Accessibility**: Ensure content is usable by all
### **Collaboration Tools**
- **Version control**: Track changes and history
- **Review systems**: Collect feedback and approvals
- **Analytics**: Understand usage patterns
- **Notifications**: Keep team informed of updates
## Implementation Next Steps
1. **Review existing documentation**: Apply these principles to current docs
2. **Identify gaps**: What documentation is missing or outdated?
3. **Plan improvements**: Prioritize documentation updates
4. **Establish processes**: Set up regular review and update cycles
---
**Last Updated**: 2025-08-17
**Version**: 2.0
**Maintainer**: Matthew Raymer
**Stakeholders**: All Teams
**Next Review**: 2025-09-17

570
.cursor/rules/docs/markdown.mdc Normal file
View File

@@ -0,0 +1,570 @@
# Cursor Markdown Ruleset for TimeSafari Documentation
## Overview
This ruleset enforces consistent markdown formatting standards across all project
documentation, ensuring readability, maintainability, and compliance with
markdownlint best practices. **LLMs must follow these rules strictly to generate
lint-free documentation.**
## General Formatting Standards
### Line Length
- **Maximum line length**: 80 characters
- **Exception**: Code blocks (JSON, shell, TypeScript, etc.) - no line length
enforcement
- **Rationale**: Ensures readability across different screen sizes and terminal
widths
- **LLM Guidance**: Always count characters and break lines at 80 characters
unless in code blocks
### Blank Lines
- **Headings**: Must be surrounded by blank lines above and below
- **Lists**: Must be surrounded by blank lines above and below
- **Code blocks**: Must be surrounded by blank lines above and below
- **Maximum consecutive blank lines**: 1 (no multiple blank lines)
- **File start**: No blank lines at the beginning of the file
- **File end**: Single newline character at the end
- **LLM Guidance**: Always add blank lines around structural elements
### Whitespace
- **No trailing spaces**: Remove all trailing whitespace from lines
- **No tabs**: Use spaces for indentation
- **Consistent indentation**: 2 spaces for list items and nested content
- **LLM Guidance**: Use space characters only, never tabs
## Heading Standards
### Format
- **Style**: ATX-style headings (`#`, `##`, `###`, etc.)
- **Case**: Title case for general headings
- **Code references**: Use backticks for file names and technical terms
- ✅ `### Current package.json Scripts`
- ❌ `### Current Package.json Scripts`
- **LLM Guidance**: Always use ATX style, never use Setext style (`===` or `---`)
### Hierarchy
- **H1 (#)**: Document title only - **ONE PER DOCUMENT**
- **H2 (##)**: Major sections
- **H3 (###)**: Subsections
- **H4 (####)**: Sub-subsections
- **H5+**: Avoid deeper nesting
- **LLM Guidance**: Start every document with exactly one H1, maintain logical
hierarchy
### Heading Content Rules
- **No trailing punctuation**: Avoid periods, colons, etc. at end
- **No duplicate headings**: Each heading must be unique within the document
- **Descriptive but concise**: Headings should clearly describe the section
- **LLM Guidance**: Use action-oriented headings, avoid generic terms like
"Overview"
## List Standards
### Unordered Lists
- **Marker**: Use `-` (hyphen) consistently
- **Indentation**: 2 spaces for nested items
- **Blank lines**: Surround lists with blank lines
- **LLM Guidance**: Always use hyphens, never use asterisks or plus signs
### Ordered Lists
- **Format**: `1.`, `2.`, `3.` (sequential numbering)
- **Indentation**: 2 spaces for nested items
- **Blank lines**: Surround lists with blank lines
- **LLM Guidance**: Use sequential numbers, never skip numbers or use random
numbers
### Task Lists
- **Format**: `- [ ]` for incomplete, `- [x]` for complete
- **Use case**: Project planning, checklists, implementation tracking
- **LLM Guidance**: Use consistent spacing in brackets `[ ]` not `[ ]`
## Code Block Standards
### Fenced Code Blocks
- **Syntax**: Triple backticks with language specification
- **Languages**: `json`, `bash`, `typescript`, `javascript`, `yaml`, `markdown`
- **Blank lines**: Must be surrounded by blank lines above and below
- **Line length**: No enforcement within code blocks
- **LLM Guidance**: Always specify language, never use generic code blocks
### Inline Code
- **Format**: Single backticks for inline code references
- **Use case**: File names, commands, variables, properties
- **LLM Guidance**: Use backticks for any technical term, file path, or command
## Special Content Standards
### JSON Examples
```json
{
"property": "value",
"nested": {
"property": "value"
}
}
```
### Shell Commands
```bash
# Command with comment
npm run build:web
# Multi-line command
VITE_GIT_HASH=`git log -1 --pretty=format:%h` \
vite build --config vite.config.web.mts
```
### TypeScript Examples
```typescript
// Function with JSDoc
/**
* Get environment configuration
* @param env - Environment name
* @returns Environment config object
*/
const getEnvironmentConfig = (env: string) => {
switch (env) {
case 'prod':
return { /* production settings */ };
default:
return { /* development settings */ };
}
};
```
## File Structure Standards
### Document Header
```markdown
# Document Title
**Author**: Matthew Raymer
**Date**: YYYY-MM-DD
**Status**: 🎯 **STATUS** - Brief description
## Overview
Brief description of the document's purpose and scope.
```
### Section Organization
1. **Overview/Introduction**
2. **Current State Analysis**
3. **Implementation Plan**
4. **Technical Details**
5. **Testing & Validation**
6. **Next Steps**
## Enhanced Markdownlint Configuration
### Required Rules (Comprehensive)
```json
{
"MD013": { "code_blocks": false, "line_length": 80 },
"MD012": true,
"MD022": true,
"MD031": true,
"MD032": true,
"MD047": true,
"MD009": true,
"MD024": true,
"MD025": true,
"MD026": { "punctuation": ".,;:!" },
"MD029": { "style": "ordered" },
"MD030": { "ul_single": 1, "ol_single": 1, "ul_multi": 1, "ol_multi": 1 },
"MD033": false,
"MD041": true,
"MD046": { "style": "fenced" },
"MD018": true,
"MD019": true,
"MD020": true,
"MD021": true,
"MD023": true,
"MD027": true,
"MD028": true,
"MD036": true,
"MD037": true,
"MD038": true,
"MD039": true,
"MD040": true,
"MD042": true,
"MD043": true,
"MD044": true,
"MD045": true
}
```
### Rule Explanations (LLM Must Follow)
- **MD013**: Line length (80 chars max, disabled for code blocks)
- **MD012**: No multiple consecutive blank lines
- **MD022**: Headings must be surrounded by blank lines
- **MD031**: Fenced code blocks must be surrounded by blank lines
- **MD032**: Lists must be surrounded by blank lines
- **MD047**: Files must end with single newline
- **MD009**: No trailing spaces
- **MD024**: No duplicate headings
- **MD025**: Only one H1 per document
- **MD026**: No trailing punctuation in headings
- **MD029**: Ordered list item prefix style
- **MD030**: List item marker styles
- **MD033**: Allow inline HTML (disabled for flexibility)
- **MD041**: First line must be top-level heading
- **MD046**: Code block style (fenced only)
- **MD018**: Heading should have space after hash
- **MD019**: Heading should have space after hash
- **MD020**: Heading should have space after hash
- **MD021**: Heading should have space after hash
- **MD023**: Heading should start at beginning of line
- **MD027**: No multiple spaces after blockquote marker
- **MD028**: No blank line inside blockquote
- **MD036**: No emphasis used for headings
- **MD037**: No spaces inside emphasis markers
- **MD038**: No spaces inside code span markers
- **MD039**: No spaces inside link text
- **MD040**: Fenced code blocks should have language specified
- **MD042**: No empty links
- **MD043**: Required heading structure
- **MD044**: Line length in code blocks
- **MD045**: No images without alt text
## LLM-Specific Language Guidelines
### **CRITICAL: LLM Must Follow These Rules**
#### 1. **Heading Generation**
- **Always start with H1**: Every document must have exactly one
`# Document Title`
- **Use descriptive headings**: Avoid generic terms like "Overview",
"Details", "Information"
- **Maintain hierarchy**: H2 for major sections, H3 for subsections
- **No duplicate headings**: Each heading must be unique within the document
#### 2. **List Formatting**
- **Unordered lists**: Always use `-` (hyphen), never `*` or `+`
- **Ordered lists**: Use sequential numbers `1.`, `2.`, `3.`
- **Consistent spacing**: Always use 2 spaces for indentation
- **Blank lines**: Surround all lists with blank lines
#### 3. **Code and Technical Content**
- **Inline code**: Use backticks for any technical term, file path, or command
- **Code blocks**: Always specify language, never use generic blocks
- **File references**: Always use backticks for file names and paths
#### 4. **Line Length Management**
- **Count characters**: Ensure no line exceeds 80 characters
- **Break naturally**: Break at word boundaries when possible
- **Code blocks**: No line length enforcement within code blocks
#### 5. **Whitespace Rules**
- **No trailing spaces**: Never leave spaces at end of lines
- **No tabs**: Use spaces only for indentation
- **Blank lines**: Use exactly one blank line between sections
## Enhanced Validation Commands
### Check Single File
```bash
npx markdownlint docs/filename.md
```
### Check All Documentation
```bash
npx markdownlint docs/
```
### Check with Custom Config
```bash
npx markdownlint --config .markdownlint.json docs/
```
### Generate Detailed Report
```bash
npx markdownlint --config .markdownlint.json --output markdownlint-report.txt docs/
```
### Check Specific Rules
```bash
npx markdownlint --rules MD013,MD012,MD022,MD024,MD025 docs/
```
### Project-Wide Validation
```bash
# Check all markdown files in project
find . -name "*.md" -exec npx markdownlint {} \;
# Check specific directories
npx markdownlint .cursor/rules/ docs/ README.md
# Check with verbose output
npx markdownlint --verbose docs/
```
### Auto-fix Common Issues
```bash
# Remove trailing spaces
sed -i 's/[[:space:]]*$//' docs/filename.md
# Remove multiple blank lines
sed -i '/^$/N;/^\n$/D' docs/filename.md
# Add newline at end if missing
echo "" >> docs/filename.md
# Fix heading spacing
sed -i 's/^# /# /g' docs/filename.md
```
## Common Patterns
### Implementation Plans
```markdown
## Implementation Plan
### Phase 1: Foundation
#### 1.1 Component Setup
- [ ] Create new component file
- [ ] Add basic structure
- [ ] Implement core functionality
#### 1.2 Configuration
- [ ] Update configuration files
- [ ] Add environment variables
- [ ] Test configuration loading
```
### Status Tracking
```markdown
**Status**: ✅ **COMPLETE** - All phases finished
**Progress**: 75% (15/20 components)
**Next**: Ready for testing phase
```
### Performance Metrics
```markdown
#### 📊 Performance Metrics
- **Build Time**: 2.3 seconds (50% faster than baseline)
- **Bundle Size**: 1.2MB (30% reduction)
- **Success Rate**: 100% (no failures in 50 builds)
```
## Enforcement
### Pre-commit Hooks
```bash
#!/bin/bash
# .git/hooks/pre-commit
# Check markdown files before commit
echo "Running markdownlint..."
# Get list of staged markdown files
staged_md_files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.md$')
if [ -n "$staged_md_files" ]; then
echo "Checking markdown files: $staged_md_files"
# Run markdownlint on staged files
npx markdownlint $staged_md_files
if [ $? -ne 0 ]; then
echo "❌ Markdown linting failed. Please fix issues before committing."
exit 1
fi
echo "✅ Markdown linting passed."
fi
```
### CI/CD Integration
```yaml
# .github/workflows/markdown-lint.yml
name: Markdown Lint
on:
push:
paths: ['**/*.md']
pull_request:
paths: ['**/*.md']
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Install markdownlint
run: npm install -g markdownlint-cli
- name: Run markdownlint
run: markdownlint --config .markdownlint.json .
- name: Generate report
run: markdownlint --config .markdownlint.json --output lint-report.txt .
- name: Upload report
uses: actions/upload-artifact@v3
with:
name: markdown-lint-report
path: lint-report.txt
```
### Team Guidelines
- All documentation PRs must pass markdownlint
- Use provided templates for new documents
- Follow established patterns for consistency
- **LLM-generated content must pass all linting rules**
## Templates
### New Document Template
```markdown
# Document Title
**Author**: Matthew Raymer
**Date**: YYYY-MM-DD
**Status**: 🎯 **PLANNING** - Ready for Implementation
## Overview
Brief description of the document's purpose and scope.
## Current State
Description of current situation or problem.
## Implementation Plan
### Phase 1: Foundation
- [ ] Task 1
- [ ] Task 2
## Next Steps
1. **Review and approve plan**
2. **Begin implementation**
3. **Test and validate**
---
**Status**: Ready for implementation
**Priority**: Medium
**Estimated Effort**: X days
**Dependencies**: None
**Stakeholders**: Development team
```
### Rule File Template
```markdown
# Rule Name
**Purpose**: Brief description of what this rule accomplishes
## Overview
Detailed explanation of the rule's scope and importance.
## Implementation
### Requirements
- [ ] Requirement 1
- [ ] Requirement 2
### Examples
#### ✅ Good Example
```markdown
# Good example content
```
#### ❌ Bad Example
```markdown
# Bad example content
```
## Validation
How to test that this rule is working correctly.
---
**Status**: Active
**Version**: 1.0
**Maintainer**: Matthew Raymer
## LLM Quality Assurance Checklist
### **Before Generating Documentation, LLM Must:**
- [ ] **Understand line length**: No line over 80 characters
- [ ] **Plan heading structure**: One H1, logical hierarchy, no duplicates
- [ ] **Choose list markers**: Hyphens for unordered, sequential numbers for ordered
- [ ] **Plan code blocks**: Specify languages, add blank lines around
- [ ] **Check whitespace**: No trailing spaces, consistent indentation
- [ ] **Validate structure**: Proper blank line placement
### **After Generating Documentation, LLM Must:**
- [ ] **Verify line lengths**: Count characters, break long lines
- [ ] **Check heading hierarchy**: Ensure logical structure
- [ ] **Validate lists**: Consistent markers and spacing
- [ ] **Review code blocks**: Proper language specification
- [ ] **Clean whitespace**: Remove trailing spaces, add proper blank lines
- [ ] **Test with markdownlint**: Ensure all rules pass
---
**Last Updated**: 2025-08-17
**Version**: 2.0
**Maintainer**: Matthew Raymer
**LLM Compliance**: Required for all documentation generation