Cursor Composer Agent Documentation Style_guide_rules

documentation_style_guide.rmd

---
title: "Multi-Pass Documentation Patterns"
author: "Roul-App Development Team"
date: "`r format(Sys.time(), '%B %d, %Y')`"
output:
  html_document:
    theme: united
    highlight: tango
    toc: yes
    toc_depth: 3
    toc_float: yes
    code_folding: show
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  echo = FALSE,
  warning = FALSE,
  message = FALSE,
  fig.width = 10,
  fig.height = 6,
  dev = "svg"
)

library(tidyverse)
library(DiagrammeR)
library(DT)
```
# Related Cursor Forum Links:
# https://forum.cursor.com/t/development-diary-and-diary-for-context-continuity-with-agent-composer/36184
# https://forum.cursor.com/t/composer-ui-is-fantastic/36129/3

#####

# Documentation Evolution Patterns

## The Multi-Pass Approach

Our roulette project documentation demonstrates how to effectively implement multi-pass documentation that builds layers of understanding while maintaining coherence.

```{mermaid}
graph TD
    A[Raw Technical Data] --> B[Structured Bullets]
    B --> C[Narrative Prose]
    C --> D[Visual Elements]
    D --> E[Interactive Components]
    
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:2px
    style C fill:#dfd,stroke:#333,stroke-width:2px
    style D fill:#fdd,stroke:#333,stroke-width:2px
    style E fill:#dff,stroke:#333,stroke-width:2px
```

### Layer 1: Technical Extraction
```{r layer1-example, echo=TRUE}
# Initial technical extraction
technical_components <- list(
  physics = c("Forces", "Integration", "Collisions"),
  geometry = c("Wheel Layout", "Trajectories", "Sectors"),
  analysis = c("Probability", "Distribution", "Outcomes")
)
```

### Layer 2: Structured Knowledge
```{r layer2-example}
# Create a structured knowledge table
knowledge_df <- data.frame(
  Component = names(technical_components),
  Elements = sapply(technical_components, length),
  Complexity = c("High", "Medium", "High")
)

DT::datatable(knowledge_df)
```

### Layer 3: Narrative Integration

The transformation from bullets to narrative:

**Before:**
```markdown
* Force calculations
  * Gravity
  * Normal force
  * Friction
* Integration method
  * Velocity Verlet
  * Error bounds
```

**After:**
```markdown
The physics engine implements a comprehensive force model that accounts for 
gravitational effects, normal forces, and friction. These forces are 
integrated using the Velocity Verlet method, chosen for its superior 
energy conservation properties and bounded error characteristics.
```

### Layer 4: Visual Enhancement

```{r visual-example}
# Create a visualization of the documentation flow
grViz("
  digraph doc_flow {
    rankdir = LR;
    node [shape = box, style = rounded];
    
    extract [label = 'Extract\nTechnical\nDetails']
    structure [label = 'Structure\nContent']
    narrate [label = 'Create\nNarrative']
    visualize [label = 'Add\nVisuals']
    interact [label = 'Implement\nInteractivity']
    
    extract -> structure -> narrate -> visualize -> interact
    
    {rank = same; extract structure narrate visualize interact}
  }
")
```

## Tool Selection Strategy

Our documentation process uses a strategic combination of tools:

```{r tool-strategy}
tools_df <- data.frame(
  Phase = c("Discovery", "Analysis", "Integration", "Visualization", "Validation"),
  Primary_Tool = c("Semantic Search", "Grep Search", "File Reading", "D3.js/R", "Linting"),
  Purpose = c(
    "Broad context gathering",
    "Specific implementation details",
    "Deep understanding",
    "Interactive representation",
    "Quality assurance"
  )
)

DT::datatable(tools_df)
```

## Context Constraint Patterns

```{mermaid}
graph LR
    A[Global Context] --> B[Domain Context]
    B --> C[Component Context]
    C --> D[Implementation Context]
    
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:2px
    style C fill:#dfd,stroke:#333,stroke-width:2px
    style D fill:#fdd,stroke:#333,stroke-width:2px
```

### Example: Physics Documentation

1. **Global Context**: Roulette simulation system
2. **Domain Context**: Physics engine component
3. **Component Context**: Force calculation module
4. **Implementation Context**: Velocity Verlet integration

## Dependency Analysis Pattern

```{r dependency-flow}
grViz("
  digraph dep_flow {
    rankdir = TB;
    node [shape = box, style = rounded];
    
    search1 [label = 'Primary\nSearch']
    deps1 [label = 'First-Order\nDependencies']
    search2 [label = 'Secondary\nSearch']
    deps2 [label = 'Second-Order\nDependencies']
    integrate [label = 'Integration\nAnalysis']
    
    search1 -> deps1 -> search2 -> deps2 -> integrate
  }
")
```

## Template Customization

Our documentation uses template inheritance patterns:

```{mermaid}
classDiagram
    class BaseTemplate {
        +header()
        +content_structure()
        +footer()
    }
    class TechnicalDoc {
        +equations()
        +code_samples()
    }
    class VisualDoc {
        +diagrams()
        +interactive_elements()
    }
    BaseTemplate <|-- TechnicalDoc
    BaseTemplate <|-- VisualDoc
```

## Practical Implementation

### 1. Multi-Pass Documentation Example

```{r doc-evolution}
# Example of documentation evolution
doc_evolution <- data.frame(
  Pass = c("Initial", "Structure", "Narrative", "Visual", "Interactive"),
  Input = c("Raw Data", "Bullets", "Structure", "Prose", "Diagrams"),
  Output = c("Bullets", "Structure", "Prose", "Diagrams", "Interactive"),
  Tool = c("Extraction", "Organization", "Writing", "D3/R", "JavaScript")
)

DT::datatable(doc_evolution)
```

### 2. Context Management

```{r context-management}
grViz("
  digraph context {
    rankdir = TB;
    node [shape = box, style = rounded];
    
    global [label = 'Global\nContext']
    domain [label = 'Domain\nContext']
    component [label = 'Component\nContext']
    
    subgraph cluster_0 {
      label = 'Search Strategy'
      semantic [label = 'Semantic\nSearch']
      grep [label = 'Grep\nSearch']
      file [label = 'File\nReading']
    }
    
    global -> semantic
    domain -> grep
    component -> file
  }
")
```

## Best Practices

1. **Progressive Enhancement**
   - Start with core technical content
   - Add structure incrementally
   - Enhance with visuals
   - Implement interactivity

2. **Tool Selection**
   - Use semantic search for broad context
   - Apply grep for specific details
   - Implement file reading for deep understanding
   - Integrate visualization tools for clarity

3. **Quality Assurance**
   - Validate technical accuracy
   - Ensure narrative flow
   - Test interactive elements
   - Verify cross-references

## Conclusion

The multi-pass documentation approach allows for:
- Natural content evolution
- Progressive enhancement
- Proper tool selection
- Comprehensive coverage
- Maintainable structure

This methodology has proven effective in our roulette project documentation, producing clear, comprehensive, and engaging technical documentation.

https://i.imgur.com/g5kG1S2.png