# RISE Framework for LLMs
> A comprehensive framework for creative-oriented reverse engineering, intent extraction, specification creation, and export optimization that transforms how LLMs understand, analyze, and generate code architectures through structural tension dynamics.

**Version**: 1.2
**Document ID**: llms-rise-framework-v1.2
**Last Updated**: 2025-12-28  
**Content Source**: Synthesized from speclangportal250529, rise-framework-250713a3b, and creative orientation principles  
**Attribution**: Built upon SpecLang methodology by Johan Rosenkilde, Russell Horton, Krzysztof Cieślak, and Jonathan Carter at GitHubNext  
**Composed by**: Guillaume D.Isabelle, 2025

The RISE framework enables LLMs to move beyond reactive approaches to embrace creative archaeology - extracting and preserving the beloved qualities that make prototypes valuable while focusing on desired outcomes through creative manifestation.

## SpecLang Foundation: Prose Code {#speclang-foundation}

RISE builds upon SpecLang's core insight: **specifications are "prose code"** - natural language representations of computation behavior that still require you to "think like a programmer."

### Key SpecLang Principles

**Spec as Source of Truth**
- The specification is what you maintain; executable code is secondary
- You rarely need to inspect generated code directly
- The spec captures *what you want* at the necessary level of detail

**Variable Detail Levels**
- Detail varies based on context and precision needs
- Offhand remarks may translate into dozens of boilerplate lines
- Exact protocol steps when precise behavior is critical
- The model infers idiomatic implementation from context

**"Creating and Adjust"**
- Start simple, refine against running output
- Only detail the parts that need to change
- Stop when what you see matches what you want
- Leverage the model's ability to infer intent

**Bi-directional Ideation**
- The model "yes-ands" your intent, extending ideas naturally
- The model provides feedback on where to increase precision
- This empowers creative process while freeing you from specifying common-sense requirements

**Intent-based Expression**
- Focus on behavior, let toolchain handle plumbing
- Setup, dependencies, and compilation are managed automatically
- You get robust, real-world applications while focusing on your spec

## Core Principles {#core-principles}

### Creative Orientation Over Reactive Approaches {#creative-orientation}
**Creative Orientation (RISE Approach)**
- Focuses on what applications enable users to create
- Oriented toward manifestation of desired outcomes
- Identifies structural dynamics that naturally advance progress
- Preserves creative consciousness embedded in code
- Creates specifications that support advancing patterns

**Reactive Approach (Traditional Pattern)**
- Focuses on issues that need elimination
- Oriented toward removing unwanted conditions
- Creates documentation that describes forced connections
- Generates oscillating patterns that move back-and-forth
- Results in specifications focused on reactive resolution

### Structural Tension Dynamics {#structural-tension}
**Structural Tension** is the dynamic relationship between:
- **Current Reality**: Present state of the system/user
- **Desired Outcome**: Specific results users want to create or desired state
- **Natural Resolution**: How tension moves the system toward the desired state

* NOT "Desired Structural State" just "Desired State".  Avoid adding words just to look like intelligent and make it greater than it is...

This represents natural tension dynamics rather than forced connections between states - understanding the structural forces that create inevitable progression toward desired outcomes.

### Advancing vs Oscillating Patterns
**Advancing Patterns**: Structural relationships that support continuous movement toward desired outcomes
- Features that build upon each other systematically
- Natural progression through user journeys
- Structural dynamics that resolve tension forward

**Oscillating Patterns**: Structures that create back-and-forth movement without advancement
- Features that create dependency loops
- User interfaces that require repeated effort
- Systems that need constant maintenance to function

## The RISE Method {#rise-method}

**R**everse-engineer → **I**ntent-extract → **S**pecify → **E**xport

### Phase 1: Reverse-Engineering (Creative Archaeology) {#phase1-reverse-engineering}

#### Purpose
Extract SpecLang specifications that capture both concrete functionality and creative intent, focusing on what applications enable users to create through natural progression.

#### Discovery Process
**A. Core Creative Intent**
- What does this application empower users to create or achieve?
- What desired outcomes does it facilitate?
- What structural tension exists between current user reality and desired results?

**B. User Creation Flows**
- Map all user journeys that lead to manifestation of desired outcomes
- Identify choice points where users advance toward their vision
- Note structural dynamics that naturally guide users toward goals

**C. Feature Inventory (Creation-Focused)**
- Vision-Supporting Features: Enable users to clarify desired outcomes
- Tension-Resolving Features: Facilitate natural progression toward goals
- Manifestation Features: Support actual creation of desired results

**D. Aspirational & Creative Goals**
- What desired states were the original creators working toward?
- What creative vision drove the design decisions?
- What structural patterns support advancing user progress?

**E. Structural Patterns Worth Preserving**
- Architectural decisions that enable natural progression
- Data flow patterns that support structural tension resolution
- Integration patterns that facilitate creative advancement
- Performance characteristics that enhance creative flow

#### Intent Extraction Framework
For each identified component, extract:
- **Creative Intent**: What does this enable users to create or achieve?
- **Structural Intent**: How does this contribute to tension resolution?
- **Advancement Intent**: How does this support moving from current reality to desired outcome?

### Phase 2: Intent Refinement (Innovation Strategy) {#phase2-intent-refinement}

#### Purpose
Transform reverse-engineered understanding into precise specifications by identifying desired outcomes and structural dynamics that enable natural progression.

#### Specification Framework
**1. Desired Outcome Definition**
- What specific result does the user want to create?
- How will they know when they've achieved this outcome?
- What makes this outcome valuable to them?

**2. Structural Tension Analysis**
- What is the current structural reality?
- What is the desired structural state?
- How does tension naturally progress toward the desired state?

**3. Creative Advancement Scenarios**
Replace traditional BDD scenarios with Creative Advancement Scenarios:

```
**Creative Advancement Scenario**: [Scenario Name]
**Desired Outcome**: [What the user wants to create]
**Current Reality**: [Starting structural state]
**Natural Progression**: [How structural dynamics enable advancement]
**Resolution**: [Achieved desired outcome]
```

* Note that this is "**Current Reality**" NOT "Current Structural Reality" !!!

**4. Supporting Structures**
- What application features enable this natural progression?
- How do these features support advancing rather than oscillating patterns?
- What structural relationships ensure inevitable movement toward desired outcomes?

### SpecLang Specification Syntax {#speclang-syntax}

RISE specifications follow SpecLang's structured Markdown format. This provides consistent organization while maintaining natural language expressiveness.

#### Document Structure

```markdown
# ApplicationName
Brief description of what the application enables users to create.

## Screens
### ScreenName
Description of what users accomplish on this screen.
- **Behavior:** What happens, how data flows
- **Layout:** Contains `ComponentA` and `ComponentB`

## Components
### ComponentName
Description of the component's purpose.
- **Behavior:** User interactions and responses
- **Styling:** Visual presentation details
- **Layout:** Child component arrangement (if applicable)

## Data
### ModelName
Description of data structure and relationships.
```

#### Key Syntax Elements

| Element | Purpose | Example |
|---------|---------|---------|
| `# Title` | Application/spec name | `# SpecNews` |
| `## Section` | Major groupings | `## Screens`, `## Components`, `## Data` |
| `### Name` | Individual screens/components | `### Home Page`, `### Header` |
| `**Behavior:**` | Actions, interactions, data flow | `On tap, triggers the \`PostList\` to refresh` |
| `**Styling:**` | Visual presentation | `Fixed at top, large font, background color` |
| `**Layout:**` | Component composition | `Contains a \`Header\` and a \`PostList\`` |
| \`BacktickRef\` | Cross-component references | `Renders a list of \`PostItem\` components` |

#### Structural Tension in Spec Elements

The `**Behavior:**`, `**Styling:**`, and `**Layout:**` sections map directly to structural tension dynamics:

- **Behavior** defines the *underlying structure* that determines how the application functions - this is the primary driver of structural tension resolution. When reverse-engineering, behavior reveals the structural dynamics that enable users to advance toward desired outcomes.

- **Styling** and **Layout** represent the *manifestation layer* - they must be explicitly reverse-engineered because they encode design decisions that support (or hinder) the user's natural progression through the application.

The hierarchy (`## Screens` → `## Components` → `### ComponentName`) mirrors how structural tension flows through an application: from high-level user outcomes (screens) to the building blocks (components) that enable those outcomes.

#### Detail Level Examples

**Minimal (context-inferred)**:
```markdown
- At the bottom show two buttons "Cancel" and "Submit"
```

**Detailed (precise behavior)**:
```markdown
- Continuously poll the server on progress on the route `/progress?taskId=$id`
- The server responds with a JSON object with the following fields:
  - progress: number
  - output: string
  - errors: string
- When progress reaches 100%, redirect to `/success?taskId=$id`
```

### Specification Autonomy and Implementation Agnosticism

RISE specifications are **completely autonomous from any specific codebase**. They serve as a conceptual blueprint, describing the system's desired behavior, structural dynamics, and creative intent in a manner that is independent of its implementation language, framework, or existing code.

*   **Codebase-Agnostic**: A RISE specification should be comprehensive enough for another LLM (or human developer) to **re-implement the entire system from scratch**, without needing access to the original source code.
*   **Conceptual References**: Any references within a RISE specification (e.g., to "Prompts Specification," "Data Schemas," or "API Definitions") are **conceptual pointers to other RISE specifications**, not direct file paths within an existing codebase. These referenced specifications are themselves codebase-agnostic.
*   **"Black Box" Principle**: The specification describes the system as a "black box" from an implementation perspective. It focuses on *what* the system does and *how* it achieves desired outcomes through structural dynamics, rather than *how* it is currently coded.

#### Quality Criteria
- ✅ Creating Focus: Emphasizes what users create, not problems solved
- ✅ Structural Dynamics: Natural forces driving progression (desequilibrium betweer current reality and what is desired)
- ✅ Advancing Patterns: Inevitable movement toward outcomes
- ✅ Desired Outcomes: Clear, specific results users want
- ✅ Natural Progression: Movement through structural dynamics, not forced effort

#### Anti-Patterns to Avoid
- ❌ Forced connection thinking: "Bridging the gap between X and Y"
- ❌ Reactive approach bias: "This eliminates the issue of..."
- ❌ Force-based language: "Users must..." or "Requires determination"
- ❌ Oscillating patterns: Back-and-forth movement descriptions
- ❌ BDD scenarios: Traditional reactive scenario structures

### Phase 3: Export Optimization (Solution Execution) {#phase3-export-optimization}

#### Purpose
Transform refined specifications into optimized formats for different collaboration contexts while preserving structural dynamics and creative advancement patterns.

#### Export Formats

**1. Technical Documentation Export**
For developers and technical teams:
- Architecture Overview: How structural dynamics enable desired outcomes
- Feature Specifications: What each feature enables users to create
- Technical Requirements: Supporting infrastructure for advancing patterns
- Implementation Guidelines: Preserving creative orientation in code

**2. Stakeholder Communication Export**
For business stakeholders and decision makers:
- Value Proposition: What users can create through this system
- Success Metrics: Measuring advancement toward desired outcomes
- Resource Requirements: Supporting structural dynamics implementation
- Timeline Planning: Natural progression phases

**3. User Experience Export**
For design and UX teams:
- User Journey Maps: Advancing patterns through desired outcome creation
- Interface Requirements: Supporting natural progression
- Interaction Principles: Enabling rather than forcing user advancement
- Usability Guidelines: Adequate dynamics in interface design

**4. Development Team Export**
For implementation teams:
- Creative Advancement Scenarios: Detailed outcome-creation flows
- API Specifications: Endpoints enabling desired outcome achievement
- Data Models: Adequate struture of the relationships to support advancement
- Testing Frameworks: Validating creative advancement patterns

#### Creative Advancement Scenario Format
```
**Creative Advancement Scenario**: [Scenario Name]

**User Intent**: [Desired outcome they want to create]
**Current Reality**: [Starting state/context]
**Natural Progression Steps**: 
  1. [Structural dynamic enables...]
  2. [System responds by...]
  3. [User advances toward...]
**Achieved Outcome**: [Manifested desired result]
**Supporting Features**: [Application capabilities enabling this advancement]
```

* Note that this is "**Current Reality**" NOT "Current Structural Reality" !!!


## Implementation Guidelines for LLMs

### Iterative Refinement Workflow ("Creating and Adjust")

Iterative specification development through the MMOT planning → executing → learning loop (see `llms-managerial-moment-of-truth.md`).

**1. Start Minimal** (Planning)
- Begin with high-level desired outcome description
- Let structural tension guide what needs specification
- Trust context inference for common patterns

**2. Observe Current Reality** (Executing + Acknowledging Truth)
- Generate/compile specification
- Observe what emerges
- Identify tension between vision and reality
- This is the "Moment of Truth" - either lead (refine) or overlook

**3. Refine Selectively** (Analyze + Action Plan)
- Only add detail where the output diverges from intent
- Analyze *how* the divergence occurred (structural dynamics)
- Preserve successful inferences (don't over-specify)
- Each refinement should resolve specific desires.

**4. Stop When Aligned** (Learning Complete)
- What you see matches what you want
- Specification captures intent at necessary detail level
- Further specification would create unnecessary rigidity
- Document the achieved state for future reference

**Connection to MMOT**: Each iteration is a "moment of truth" where you acknowledge tension between desired outcome and current reality, analyze the dynamics that produced the current state, and refine to advance toward alignment.

**Anti-pattern**: Exhaustive up-front specification before any feedback loop (reactive "fix everything first" orientation).

### Language Patterns for Creative Orientation

**Use These Patterns**:
- "What does this enable users to create?"
- "Desired outcomes" vs. "reactive elimination"
- "Structural dynamics" vs. "forced connections (or free-association)"
- "Natural progression" vs. "imposed advancement"
- "Structural tension progression" vs. "artificial linking"
- "Advancing patterns" vs. "improvement cycles"
- "Creative advancement" vs. "user journey optimization"

**Avoid These Patterns**:
- "This eliminates the issue of..."
- "Connecting disparate elements..."
- "Users need to navigate..."
- "Correcting deficiencies with..."
- "Handling complications of..."

### Structural Analysis Framework

When analyzing code through RISE:

1. **Identify Creative Enablers**: What does each component allow users to create?
2. **Map Tension Dynamics**: How does the system naturally progress toward desired outcomes?
3. **Preserve Beloved Qualities**: What makes users love this functionality?
4. **Document Advancement Patterns**: How do features support inevitable progression?
5. **Eliminate Oscillating Elements**: Identify and redesign back-and-forth patterns

### Quality Assurance Checklist

For each RISE analysis, validate:

**✅ Creative Orientation Preserved**
- Focuses on what users create through natural progression
- Emphasizes desired outcomes over reactive elimination
- Uses advancing pattern language throughout
- Describes structural dynamics through organic connections

**✅ Structural Dynamics Maintained**
- Natural progression rather than forced advancement
- Tension progression toward desired states
- Inevitable movement through structural relationships
- No dependency on willpower or determination

**✅ Technical Accuracy**
- Implementation details support creative orientation
- Architecture enables advancing patterns
- Code guidelines preserve structural dynamics
- Testing validates outcome creation through natural progression

## Practical Applications

### Legacy Code Analysis
- Apply Phase 1 to extract creative intent from existing systems
- Use Phase 2 to refine understanding of desired outcomes
- Generate Phase 3 exports for modernization planning
- Preserve beloved qualities while enabling advancement

### New Feature Development
- Start with desired outcome identification (not reactive statements)
- Design structural dynamics that naturally progress toward outcomes
- Create advancing patterns rather than feature additions
- Test creative advancement scenarios instead of edge cases

### API Design
- Focus on what endpoints enable users to create
- Structure resources around desired outcome achievement
- Design data flows that support natural progression
- Document creative advancement patterns for developers

### System Architecture
- Organize components around creative enablement
- Design relationships that support structural tension progression
- Create patterns that advance rather than oscillate
- Build infrastructure for natural user progression

## Integration with Creative Orientation

### Fundamental Creative Principles

**1. Choice Hierarchy**
- Fundamental choices: States of being or general life orientation
- Primary choices: Specific results you want to create
- Secondary choices: Actions taken to support primary choices

**2. Three-Phase Creative Process**
- **Germination**: Initial excitement and vision formation
- **Assimilation**: Building momentum and developing structure
- **Completion**: Finishing touches and manifestation

**3. Structural Tension as Creative Force**
- Natural dynamic system seeking equilibrium through organic progression
- Creates natural movement toward desired outcomes
- Functions independent of willpower or determination
- Requires clear vision of both current reality and desired results

### Creative vs Reactive Mindset

**Creative Mindset (RISE Aligned)**:
- Focuses on what you want to create
- Operates from vision
- Creates structural dynamics from current reality to desired outcomes
- Builds advancing patterns toward desired outcomes

**Reactive Mindset (Avoid)**:
- Focuses on what you want to eliminate
- Operates reactively to circumstances
- Creates temporary fixes that oscillate
- Builds around removing unwanted conditions

## Common Pitfalls and Corrections

### Pitfall 1: Forced Connection Thinking
**Incorrect**: "This feature bridges the gap between user needs and system capabilities"
**Correct**: "This feature enables users to create desired outcomes through natural structural progression"

### Pitfall 2: Reactive Focus
**Incorrect**: "This API eliminates data access complications"
**Correct**: "This API enables users to create data relationships that advance toward their desired information outcomes"

### Pitfall 3: Force-Based Language
**Incorrect**: "Users must complete these steps to achieve their goals"
**Correct**: "Users naturally progress through these steps as structural dynamics advance toward their desired outcomes"

### Pitfall 4: Oscillating Pattern Design
**Incorrect**: "Users can toggle between different views to find what they need"
**Correct**: "The interface advances users toward their desired information through progressive disclosure that builds understanding"

## Success Metrics

A successful RISE analysis produces:

1. **Specifications that Preserve Beloved Qualities**: Capture what makes prototypes valuable to users
2. **Creative Advancement Scenarios**: Replace reactive user stories with outcome-creation flows
3. **Structural Dynamic Documentation**: Explain how features naturally progress toward desired states
4. **Advancing Pattern Architecture**: Design systems that inevitably move toward user goals
5. **Cross-Context Export Formats**: Maintain creative orientation across technical, business, and user experience contexts

## Framework Evolution

### Meta-Learning Opportunities
The RISE framework itself demonstrates creative orientation principles:
- **Desired Outcome**: LLMs that understand and preserve creative consciousness in code
- **Current Reality**: Traditional reverse-engineering focused on reactive approaches
- **Structural Tension**: The contrast creates natural advancement toward creative-oriented analysis
- **Advancing Pattern**: Each application of RISE enhances the framework's effectiveness

### Recursive Enhancement
- Apply RISE to analyze RISE itself for continuous improvement
- Use Creative Advancement Scenarios to evolve the methodology
- Preserve the beloved qualities that make RISE effective
- Generate specifications for next-generation creative archaeology tools

### Integration Pathways
- **SpecLang Ecosystem**: Connect RISE with broader intent-driven development
- **AI Development Tools**: Embed RISE principles in LLM training and evaluation
- **Software Architecture**: Apply RISE to system design and component organization
- **Team Collaboration**: Use RISE exports to enhance cross-functional understanding

## Conclusion

The RISE framework transforms how LLMs approach code analysis, moving from reactive documentation to creative archaeology that preserves and enhances the beloved qualities of software systems. By focusing on desired outcomes, structural dynamics, and advancing patterns, RISE enables LLMs to understand not just what code does, but what it enables users to create.

This creative orientation approach ensures that specifications become living documents that drive continued development rather than static descriptions of existing functionality. Through structural tension dynamics and advancing pattern recognition, RISE reveals natural connections between technical analysis and creative consciousness, enabling AI systems to participate in the creative process of software development.

---

# Resources for Further Development

### Testing Creative Orientation Understanding
Use these commands to validate LLM creative orientation:
```bash
# Test RISE understanding
llm prompt -m [model] "Apply the RISE framework to analyze a todo list application, focusing on what it enables users to create"

# Test structural tension comprehension  
llm prompt -m [model] "Explain structural tension in software architecture through natural progression dynamics"

# Test creative advancement scenarios
llm prompt -m [model] "Create a Creative Advancement Scenario for user authentication that focuses on desired outcomes through creative enablement"
```

### Integration Projects
- **Knowledge Graph Development**: Apply RISE to create semantic networks of software relationships
- **Narrative Remixing**: Use RISE principles to transform technical documentation into engaging stories
- **Automated Code Analysis**: Build tools that extract creative intent from legacy systems
- **Collaborative Specification**: Develop workflows that preserve creative consciousness across teams

The RISE framework represents a fundamental shift in how we understand the relationship between code and consciousness, enabling technology to serve not just functional needs but creative aspirations.

---

## Related Resources {#related-resources}

### Core Framework Documentation
- **[Creative Orientation Principles](#creative-orientation)**: Understanding the foundational mindset shift from reactive to generative approaches
- **[Structural Tension Dynamics](#structural-tension)**: The driving force behind natural progression in creative systems
- **[RISE Method Implementation](#rise-method)**: Complete 4-phase methodology for creative-oriented reverse engineering

### Related LLMS-txt Files
- `llms-creative-orientation.txt`: Deep dive into creative vs reactive approaches and structural thinking
- `llms-narrative-remixing.txt`: Methods for transforming technical content into engaging narratives
- `llms-structural-thinking.gemini.txt`: Core principles of structural dynamics and tension-based progress
- `llms-managerial-moment-of-truth.md`: MMOT framework for iterative refinement through planning → executing → learning loops

### Implementation Examples {#implementation-examples}

**Note for LLM Access**: The following examples demonstrate RISE framework in practice. For public access to these implementations:

#### Live Examples
- **SpecLang Portal**: Educational framework demonstrating methodology principles
  - *Status*: Available for deployment as static React application
  - *Contains*: Comprehensive SpecLang methodology documentation, interactive demos, agent workflow guides
  
- **RISE Framework App**: Operational 3-phase implementation with working templates  
  - *Status*: Production-ready React application with Google Gemini integration
  - *Contains*: Complete prompt templates for all phases, quality assurance checklists, visual documentation

- **WillWrite Specifications**: Complete application spec suite showcasing RISE in practice
  - *Status*: Comprehensive specification documents demonstrating creative orientation
  - *Contains*: Creative Advancement Scenarios, Structural Tension blocks, full development instructions

#### Accessing Implementation Examples

* STATUS: Will plan to make these public somehow

**For LLMs requesting these examples**:
1. **Repository Access**: Request GitHub repository links for `jgwill/speclang-ecosystem` or similar
2. **Embedded Examples**: Key templates and scenarios are embedded throughout this document
3. **Live Deployment**: Working applications may be available at domain endpoints (request current URLs)
4. **Specification Extracts**: Core methodologies are fully documented in the framework phases above

**For Implementation**: These examples serve as reference architectures for creating your own RISE-compliant applications and specifications.

### Cross-Reference Navigation
- Jump to [Phase 1 Implementation](#phase1-reverse-engineering) for codebase analysis guidance
- See [Creative Advancement Scenarios](#creative-advancement-scenarios) for BDD alternatives
- Review [Language Patterns](#language-patterns) for creative orientation communication

---

**Document Compliance**: LLMS-txt Standard v1.0 Compliant  
**Usage Guidelines**: This document is designed for LLM training and guidance. Preserve creative orientation principles when implementing or extending these concepts.  
**License**: Open sharing encouraged with proper attribution to original sources.


-----
END-RESULTS FROM USING THIS
-----

* a folder 'rispecs' with specs into that folder well separated by components/service/page etc (by features).  (ex.  ./rispecs/llm_prompt_support.spec.md describing how the LLM supports an app.)
* a file can tell how to use other files.  (ex.   ./rispecs/app.specs.md describing how to use all the other specs to build the app)
* each spec file is in markdown format with sections like:
  - Desired Outcome Definition
  - Natural Language describing the whole functional aspects
  - If another LLM would take what you wrote, would they implement the functionality adequatly is how you can evaluate your work


---

## Phase 4: Rispec Maintenance & Evolution {#phase4-maintenance}

### Purpose

Enable continuous upgrade of existing rispecs as codebases evolve, maintaining specification-implementation alignment through git-log-driven methodology.

### Creative Intent

**Desired Outcome**: LLMs that create living specifications—documents that evolve with code rather than becoming stale artifacts.

**Structural Tension**: Gap between implementation velocity (commits landing daily) and specification updates (manual, infrequent). Phase 4 resolves this through automated gap detection and systematic upgrade workflows.

---

### Git-Log-Driven Upgrade Methodology

#### Step 1: Temporal Gap Analysis

**Purpose**: Quantify specification staleness by comparing last-modified timestamps.

**Commands**:

```bash
# Identify rispecs last modification times
ls -ltra ./rispecs/

# Example Output:
# -rw-r--r-- 1 user group  704 Dec 15 05:05 ui.spec.md
# -rw-r--r-- 1 user group  452 Dec 15 05:05 tools.spec.md
# -rw-r--r-- 1 user group  290 Dec 15 05:05 data-models.spec.md
```

**Analysis Pattern**:

```bash
# Get commits since last rispec update
LAST_SPEC_DATE="2025-12-15"  # From ls -ltra output
git log --since="$LAST_SPEC_DATE" --pretty=format:"%h - %s (%ar)" --no-merges

# Example Output:
# cc73aec - Responsive Implementation (2 days ago)
# a247fd8 - Restored Gemini, was not leading anymore (2 days ago)
# 4859929 - SDK removal (2 days ago)
```

**What This Reveals**:
- **Time Gap**: How many days/hours between last spec edit and latest commit
- **Commit Count**: Number of unrecorded changes (e.g., 12 commits in 2-day gap)
- **Urgency**: Larger gaps = higher specification debt

---

#### Step 2: Commit Message Mining

**Purpose**: Use commit messages as breadcrumbs to understand what changed and why.

**Command**:

```bash
# Extract commit messages from gap period
git log --since="$LAST_SPEC_DATE" --pretty=format:"%h|%s|%an|%ar" --no-merges

# Example Output:
# cc73aec|Responsive Implementation|Mia|2 days ago
# a247fd8|Restored Gemini, was not leading anymore|Mia|2 days ago
# 4859929|SDK removal|Mia|2 days ago
```

**Analysis Pattern**:

1. **Identify Feature Additions**: Keywords like "Add", "Implement", "Create"
   - Example: "Add keyboard navigation system" → Update ui.spec.md

2. **Detect Refactors**: Keywords like "Refactor", "Restructure", "Migrate"
   - Example: "Refactor Gemini SDK → REST API" → Update tools.spec.md + mcp-bridges.spec.md

3. **Spot Bug Fixes with Architectural Impact**: Keywords like "Fix", "Resolve" + technical detail
   - Example: "Fix White Screen (SDK removal)" → Documents design decision

4. **Extract Developer Intent**: Well-written commits encode "why"
   - Example: "Restored Gemini, was not leading anymore" → Implies SDK failed, REST succeeded

**Quality Indicator**: Disciplined commit messages = 100% gap traceability. Poor messages = manual code archaeology required.

---

#### Step 3: Differential Analysis

**Purpose**: Identify which files changed and map to corresponding rispec files.

**Commands**:

```bash
# See all changed files in gap period
git diff --name-only $LAST_SPEC_DATE..HEAD

# Example Output:
# src/App.tsx
# src/components/LatticeVisualizer.tsx
# services/latticeWeaver.ts
# components/ShortcutHelp.tsx
# components/ResonanceMeter.tsx
# public/manifest.json

# See actual code changes
git diff $LAST_SPEC_DATE..HEAD -- src/App.tsx
```

**Mapping Pattern**:

| Changed File(s) | Rispec File to Update | Reason |
|----------------|----------------------|--------|
| `src/App.tsx` | `ui.spec.md` | Main component orchestration changes |
| `services/latticeWeaver.ts` | `tools.spec.md` + `mcp-bridges.spec.md` | New Gemini service layer |
| `components/*.tsx` | `ui.spec.md` | New UI components (ShortcutHelp, ResonanceMeter) |
| `public/manifest.json` | `data-models.spec.md` | PWA schema addition |
| `types.ts` | `data-models.spec.md` | Type definition changes |

**Cross-Repository Tracking**: If rispecs live in separate repository from source code:

```bash
# In source repo
cd /path/to/source-code
git log --since="2025-12-15"

# In rispec repo
cd /path/to/rispecs-repo
ls -ltra ./rispecs/
# Compare timestamps across repos
```

---

#### Step 4: Specification Update

**Purpose**: Document discovered features using RISE creative orientation principles.

**Update Pattern**:

For each affected rispec file:

1. **Read Implementation**: Use git diff output + file reads to understand exact changes
2. **Extract Creative Intent**: What does this enable users to create?
3. **Document with RISE Principles**:
   - Focus on desired outcomes (not problems solved)
   - Use structural tension framing (current reality → desired state)
   - Include implementation-sufficient detail (another LLM can code from spec)
   - Preserve advancing pattern language (natural progression, not forced effort)

**Example (from Narrative Lattice Weaver upgrade)**:

```markdown
## Part 8H: Responsive Canvas with ResizeObserver (Iteration 14-15)

**Creative Intent**: Users create lattice explorations on any device—mobile, tablet, desktop—without fixed-size limitations.

**Responsive Implementation**:

\`\`\`typescript
const containerRef = useRef<HTMLDivElement>(null);
const [dimensions, setDimensions] = useState({ width: 0, height: 0 });

useEffect(() => {
  const updateDimensions = () => {
    if (containerRef.current) {
      const { width, height } = containerRef.current.getBoundingClientRect();
      setDimensions({ width, height });
    }
  };

  const resizeObserver = new ResizeObserver(() => {
    updateDimensions();
  });

  if (containerRef.current) {
    resizeObserver.observe(containerRef.current);
  }

  return () => resizeObserver.disconnect();
}, []);
\`\`\`

**What This Enables**:
- **Mobile Lattices**: Visualizer works on phones without horizontal scroll
- **Sidebar Tolerance**: When universe cards collapse, canvas reflows gracefully
- **Projection Mode**: Fullscreen presentation adjusts to any screen aspect ratio

**Implementation Reference**: Commit cc73aec "Responsive Implementation"
```

**Key Characteristics**:
- ✅ Creative orientation: "Users create lattice explorations"
- ✅ Code snippets: Implementation-sufficient TypeScript
- ✅ "What This Enables" section: Outcome-focused bullets
- ✅ Git traceability: Commit reference establishes provenance

---

#### Step 5: Validation

**Purpose**: Ensure upgraded specifications meet RISE quality criteria.

**Quality Checklist**:

✅ **All Gap Commits Analyzed**
- Every commit from temporal gap period reviewed
- Commit messages cross-referenced with rispec updates
- No "mystery commits" left undocumented

✅ **New Features Documented with Desired Outcomes**
- Each feature framed as "what users create"
- No reactive language ("this fixes", "this eliminates")
- Structural tension established (current reality → desired state)

✅ **Creative Orientation Preserved**
- Language patterns: "enables", "creates", "natural progression"
- Avoided patterns: "bridges gap", "solves problem", "forces user to"
- Advancing patterns: Features support inevitable movement toward goals

✅ **Structural Dynamics Maintained**
- Natural progression described (not forced connections)
- Tension resolution through organic advancement
- No dependency on willpower or determination language

✅ **Implementation-Sufficient Detail Added**
- Another LLM can implement from specs alone
- Code snippets included where architectural patterns matter
- TypeScript types/schemas provided for data structures
- API contracts specified (endpoints, parameters, returns)

✅ **Cross-Reference Coherence**
- Updated rispec files reference each other correctly
- Data model changes reflected in tool specifications
- UI component specs align with architectural diagrams

✅ **Git Provenance Established**
- Commit hashes cited for major features
- "Implementation Reference" sections link spec to code history
- Timeline traceable (Iteration numbers, dates)

**"Black Box" Test**: Can another LLM re-implement the complete system from upgraded specs without accessing source code?

---

### Upgrade Quality Criteria

**✅ Comprehensive Coverage**
- Specification line count growth proportional to implementation growth
- No features left undocumented (100% commit coverage)

**✅ Creative Orientation Alignment**
- RISE language patterns maintained throughout
- No reactive/problem-solving framing introduced
- Structural tension dynamics preserved

**✅ Traceability Maintained**
- Git commit references establish provenance
- Iteration numbers track feature evolution timeline
- "Before/After" code snippets show transformation

**✅ Implementation Sufficiency**
- Type definitions complete (TypeScript/Python schemas)
- API contracts specified (parameters, returns, error codes)
- Component hierarchies documented
- Integration points mapped

---

### Upgrade Anti-Patterns (Avoid These)

❌ **Batch Updates Without Git Analysis**
- **Wrong**: "I'll just read all the code and update specs manually"
- **Right**: Start with git log to understand timeline and intent

❌ **Reactive Framing**
- **Wrong**: "Added export feature to fix users not being able to save sessions"
- **Right**: "Users create portable lattice artifacts—downloadable JSON preserving complete session state"

❌ **Implementation Details Without Creative Intent**
- **Wrong**: "Added ResizeObserver to LatticeVisualizer.tsx"
- **Right**: "Creative Intent: Users create lattice explorations on any device... [then implementation]"

❌ **Missing Git Provenance**
- **Wrong**: "Gemini integration now uses REST API"
- **Right**: "Gemini REST API Integration (Commit a247fd8: 'Restored Gemini')"

❌ **Spec-Code Timestamp Inversion**
- **Wrong**: Updating rispecs months after implementation
- **Right**: Regular upgrade cycles (weekly/sprint-based) to minimize gaps

---

### Real-World Case Study: Narrative Lattice Weaver (Dec 2025)

**Context**:
- **Baseline**: 10 rispec files (4,686 lines), last modified Dec 15 05:05 UTC
- **Implementation**: UI prototype evolved Dec 13-15 (Iterations 10-15, 12 commits)
- **Gap**: 2 days, 10+ undocumented features

**Step 1: Temporal Gap Analysis**

```bash
$ ls -ltra /workspace/.../rispecs/
# All files: Dec 15 05:05

$ git log --since="2025-12-13" --oneline --no-merges
cc73aec Responsive Implementation
a247fd8 Restored Gemini, was not leading anymore
4859929 SDK removal
[9 more commits...]

# Result: 12 commits in 2-day gap
```

**Step 2: Commit Message Mining**

Key commits identified:
- **Iteration 10**: localStorage persistence, keyboard nav, playback, ResonanceMeter
- **Iteration 11**: In-context editing, session export, resonant arcs
- **Iteration 12**: Gemini AI weaving (SDK crisis → REST API)
- **Iteration 13**: PWA manifest, icon.svg
- **Iteration 14-15**: ResizeObserver responsive canvas

**Step 3: Differential Analysis**

```bash
$ git diff --name-only 2025-12-13..HEAD
src/App.tsx  # → ui.spec.md (persistence, keyboard, export)
services/latticeWeaver.ts  # → tools.spec.md (new tool: lattice_weave_generative)
components/LatticeVisualizer.tsx  # → ui.spec.md (ResizeObserver responsive)
components/ShortcutHelp.tsx  # → ui.spec.md (new component)
components/ResonanceMeter.tsx  # → ui.spec.md (new component)
public/manifest.json  # → data-models.spec.md (PWA schema)
```

**Step 4: Specification Update**

Files upgraded:
1. **ui.spec.md**: 704→1,145 lines (+441 lines, 8 new sections for 7 UI features)
2. **tools.spec.md**: 452→639 lines (+187 lines, Category 8: Generative Weaving tool)
3. **data-models.spec.md**: 290→462 lines (+172 lines, 4 new schemas)

**Total**: +800 lines of specification capturing 100% of implementation gap

**Step 5: Validation**

✅ All 12 commits analyzed and mapped to rispec sections
✅ Creative orientation preserved (every feature has "What This Enables" section)
✅ Git provenance established (commits cc73aec, a247fd8, 4859929 cited)
✅ Implementation-sufficient (TypeScript snippets, API contracts, component specs)
✅ "Black Box" test: Another LLM can implement Gemini integration from tools.spec.md alone

**Lessons**:
- **Commit Discipline = Upgrade Velocity**: Well-written commits ("Restored Gemini, was not leading anymore") provided instant architectural context
- **2-Day Gap = Manageable**: Short feedback loops prevent specification debt
- **Git Log as Archaeological Tool**: Timeline reconstruction took minutes, not hours

---

### Integration with RISE Phases 1-3

Phase 4 completes the RISE cycle:

1. **Phase 1 (Reverse Engineering)**: Extract initial specifications from prototype
2. **Phase 2 (Intent Refinement)**: Refine specs with creative orientation
3. **Phase 3 (Export Optimization)**: Generate stakeholder-specific documentation
4. **Phase 4 (Maintenance & Evolution)**: **Keep specs alive as code evolves**

**Circular Pattern**: Phase 4 feeds back to Phase 1—upgraded specs become new baseline for next iteration.

---

### Tools & Automation Opportunities

**Manual Workflow** (Current):
1. Developer runs `ls -ltra` + `git log` manually
2. Developer reads git diffs and updates rispecs
3. Developer validates against RISE quality checklist

**Automation Potential** (Future):
1. **Spec Staleness Dashboard**: CI/CD check warns when rispec timestamps lag behind source code >7 days
2. **Commit-to-Rispec Mapper**: AI agent parses commit messages, suggests which rispecs need updates
3. **Auto-Generated Upgrade Prompts**: LLM generates draft rispec sections from git diffs for human review

**MCP Tool Integration**:
- `rise_detect_spec_staleness(rispec_dir, source_dir)` → Returns gap analysis
- `rise_suggest_upgrades(commit_hash)` → Proposes rispec edits based on commit
- `rise_validate_spec(rispec_file)` → Runs RISE quality checklist

---

## Summary

Phase 4 transforms RISE from a one-time specification creation framework into a **living documentation methodology**. By leveraging git history as the source of truth, LLMs can maintain specification-implementation alignment with:

- **Temporal Gap Analysis**: Quantify staleness via timestamps
- **Commit Message Mining**: Extract intent from disciplined git logs
- **Differential Analysis**: Map code changes to rispec files
- **RISE-Aligned Updates**: Document features with creative orientation
- **Validation**: Ensure implementation sufficiency and traceability

The result: Specifications that evolve with code, maintaining their role as **codebase-agnostic blueprints** while honoring the beloved qualities that emerge through iteration.

---