mirror of
https://github.com/jjbrunton/Sauci.git
synced 2026-11-01 18:19:43 +00:00
refactor(swipe): split swipe screen modules
Move swipe screen logic into hooks/services and extract state-specific UI components to keep files small while preserving existing behavior. Reference: US-002
This commit is contained in:
jjbrunton committed
1 parent
209dc652d2
commit
8d4d9d8750
55 files changed
+11127
-1681
No files matched your search
@@ -0,0 +1,126 @@
|
||||
# Context Engineering Reference
|
||||
|
||||
This document explains the malloc/free metaphor for LLM context management that underlies the Ralph technique.
|
||||
|
||||
## The malloc() Metaphor
|
||||
|
||||
In traditional programming:
|
||||
- `malloc()` allocates memory
|
||||
- `free()` releases memory
|
||||
- Memory leaks occur when you allocate without freeing
|
||||
|
||||
In LLM context:
|
||||
- Reading files, receiving responses, tool outputs = `malloc()`
|
||||
- **There is no `free()`** - context cannot be released
|
||||
- The only way to "free" is to start a new conversation
|
||||
|
||||
## Why This Matters
|
||||
|
||||
### Context Pollution
|
||||
|
||||
When you work on multiple unrelated tasks in the same context:
|
||||
|
||||
```
|
||||
Task 1: Build authentication → context contains auth code, JWT docs, security patterns
|
||||
Task 2: Build UI components → context now ALSO contains auth stuff
|
||||
|
||||
Result: LLM might suggest auth-related patterns when building UI
|
||||
or mix concerns inappropriately
|
||||
```
|
||||
|
||||
### Autoregressive Failure
|
||||
|
||||
LLMs predict the next token based on ALL context. When context contains:
|
||||
- Unrelated information
|
||||
- Failed attempts
|
||||
- Mixed concerns
|
||||
|
||||
The model can "spiral" into wrong territory, generating increasingly off-base responses.
|
||||
|
||||
### The Gutter Metaphor
|
||||
|
||||
> "If the bowling ball is in the gutter, there's no saving it."
|
||||
|
||||
Once context is polluted with failed attempts or mixed concerns, the model will keep referencing that pollution. Starting fresh is often faster than trying to correct course.
|
||||
|
||||
## Context Health Indicators
|
||||
|
||||
### 🟢 Healthy Context
|
||||
- Single focused task
|
||||
- Relevant files only
|
||||
- Clear progress
|
||||
- Under 60% capacity
|
||||
|
||||
### 🟡 Warning Signs
|
||||
- Multiple unrelated topics discussed
|
||||
- Several failed attempts in history
|
||||
- Approaching 80% capacity
|
||||
- Repeated similar errors
|
||||
|
||||
### 🔴 Critical / Gutter
|
||||
- Mixed concerns throughout
|
||||
- Circular failure patterns
|
||||
- Over 90% capacity
|
||||
- Model suggesting irrelevant solutions
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. One Task Per Context
|
||||
|
||||
Don't ask "fix the auth bug AND add the new feature". Do them in separate conversations.
|
||||
|
||||
### 2. Fresh Start on Topic Change
|
||||
|
||||
Finished auth? Start a new conversation for the next feature.
|
||||
|
||||
### 3. Don't Redline
|
||||
|
||||
Stay under 80% of context capacity. Quality degrades as you approach limits.
|
||||
|
||||
### 4. Recognize the Gutter
|
||||
|
||||
If you're seeing:
|
||||
- Same error 3+ times
|
||||
- Solutions that don't match the problem
|
||||
- Circular suggestions
|
||||
|
||||
Start fresh. Your progress is in the files.
|
||||
|
||||
### 5. State in Files, Not Context
|
||||
|
||||
Write progress to files. The next conversation can read them. Context is ephemeral; files are permanent.
|
||||
|
||||
## Ralph's Approach
|
||||
|
||||
The original Ralph technique (`while :; do cat PROMPT.md | agent ; done`) naturally implements these principles:
|
||||
|
||||
1. **Each iteration is a fresh process** - Context is freed
|
||||
2. **State persists in files** - Progress survives context resets
|
||||
3. **Same prompt each time** - Focused, single-task context
|
||||
4. **Failures inform guardrails** - Learning without context pollution
|
||||
|
||||
This Cursor implementation aims to bring these benefits while working within Cursor's session model.
|
||||
|
||||
## Measuring Context
|
||||
|
||||
Rough estimates:
|
||||
- 1 token ≈ 4 characters
|
||||
- Average code file: 500-2000 tokens
|
||||
- Large file: 5000+ tokens
|
||||
- Conversation history: 100-500 tokens per exchange
|
||||
|
||||
Track allocations in `.ralph/context-log.md` to stay aware.
|
||||
|
||||
## When to Start Fresh
|
||||
|
||||
**Definitely start fresh when:**
|
||||
- Switching to unrelated task
|
||||
- Context over 90% full
|
||||
- Same error 3+ times
|
||||
- Model suggestions are off-topic
|
||||
|
||||
**Consider starting fresh when:**
|
||||
- Context over 70% full
|
||||
- Significant topic shift within task
|
||||
- Feeling "stuck"
|
||||
- Multiple failed approaches in history
|
||||
@@ -0,0 +1,174 @@
|
||||
# Guardrails Reference ("Signs")
|
||||
|
||||
This document explains how to create and use guardrails in Ralph.
|
||||
|
||||
## The Signs Metaphor
|
||||
|
||||
From Geoffrey Huntley:
|
||||
|
||||
> "Ralph is very good at making playgrounds, but he comes home bruised because he fell off the slide, so one then tunes Ralph by adding a sign next to the slide saying 'SLIDE DOWN, DON'T JUMP, LOOK AROUND,' and Ralph is more likely to look and see the sign."
|
||||
|
||||
Signs are explicit instructions added to prevent known failure modes.
|
||||
|
||||
## Anatomy of a Sign
|
||||
|
||||
```markdown
|
||||
### Sign: [Descriptive Name]
|
||||
- **Trigger**: When this situation occurs
|
||||
- **Instruction**: What to do instead
|
||||
- **Added after**: When/why this was added
|
||||
- **Example**: Concrete example if helpful
|
||||
```
|
||||
|
||||
## Types of Signs
|
||||
|
||||
### 1. Preventive Signs
|
||||
|
||||
Stop problems before they happen:
|
||||
|
||||
```markdown
|
||||
### Sign: Validate Before Trust
|
||||
- **Trigger**: When receiving external input
|
||||
- **Instruction**: Always validate and sanitize input before using it
|
||||
- **Added after**: Iteration 3 - SQL injection vulnerability
|
||||
```
|
||||
|
||||
### 2. Corrective Signs
|
||||
|
||||
Fix recurring mistakes:
|
||||
|
||||
```markdown
|
||||
### Sign: Check Return Values
|
||||
- **Trigger**: When calling functions that can fail
|
||||
- **Instruction**: Always check return values and handle errors
|
||||
- **Added after**: Iteration 7 - Null pointer exception
|
||||
```
|
||||
|
||||
### 3. Process Signs
|
||||
|
||||
Enforce good practices:
|
||||
|
||||
```markdown
|
||||
### Sign: Test Before Commit
|
||||
- **Trigger**: Before committing changes
|
||||
- **Instruction**: Run the test suite and ensure all tests pass
|
||||
- **Added after**: Iteration 2 - Broken tests committed
|
||||
```
|
||||
|
||||
### 4. Architecture Signs
|
||||
|
||||
Guide design decisions:
|
||||
|
||||
```markdown
|
||||
### Sign: Single Responsibility
|
||||
- **Trigger**: When a function grows beyond 50 lines
|
||||
- **Instruction**: Consider splitting into smaller, focused functions
|
||||
- **Added after**: Iteration 12 - Unmaintainable god function
|
||||
```
|
||||
|
||||
## When to Add Signs
|
||||
|
||||
Add a sign when:
|
||||
|
||||
1. **The same mistake happens twice** - Once is learning, twice is a pattern
|
||||
2. **A subtle bug is found** - Prevent future occurrences
|
||||
3. **A best practice is violated** - Reinforce good habits
|
||||
4. **Context-specific knowledge is needed** - Project-specific conventions
|
||||
|
||||
## Sign Lifecycle
|
||||
|
||||
### Creation
|
||||
|
||||
```markdown
|
||||
### Sign: [New Sign]
|
||||
- **Trigger**: [When it applies]
|
||||
- **Instruction**: [What to do]
|
||||
- **Added after**: Iteration N - [What happened]
|
||||
```
|
||||
|
||||
### Refinement
|
||||
|
||||
If a sign isn't working:
|
||||
- Make the trigger more specific
|
||||
- Make the instruction clearer
|
||||
- Add examples
|
||||
|
||||
### Retirement
|
||||
|
||||
Signs can be removed when:
|
||||
- The underlying issue is fixed at a deeper level
|
||||
- The sign is no longer relevant
|
||||
- The sign is causing more problems than it solves
|
||||
|
||||
## Example Signs Library
|
||||
|
||||
### Security
|
||||
|
||||
```markdown
|
||||
### Sign: Sanitize All Input
|
||||
- **Trigger**: Any user-provided data
|
||||
- **Instruction**: Use parameterized queries, escape HTML, validate types
|
||||
- **Example**: `db.query("SELECT * FROM users WHERE id = ?", [userId])`
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```markdown
|
||||
### Sign: Graceful Degradation
|
||||
- **Trigger**: External service calls
|
||||
- **Instruction**: Always have a fallback for when services are unavailable
|
||||
- **Example**: Cache results, provide default values, show friendly errors
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```markdown
|
||||
### Sign: Test the Unhappy Path
|
||||
- **Trigger**: Writing tests for new functionality
|
||||
- **Instruction**: Include tests for error cases, edge cases, and invalid input
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
```markdown
|
||||
### Sign: Explain Why, Not What
|
||||
- **Trigger**: Writing comments
|
||||
- **Instruction**: Comments should explain reasoning, not describe obvious code
|
||||
- **Example**: `// Using retry because API is flaky under load` not `// Call the API`
|
||||
```
|
||||
|
||||
## Automatic Sign Detection
|
||||
|
||||
The Ralph hooks can automatically detect some patterns and suggest signs:
|
||||
|
||||
- **Thrashing**: Same file edited many times → "Step back and reconsider"
|
||||
- **Repeated errors**: Same test failing → "Check the test assumptions"
|
||||
- **Large changes**: Big diffs → "Consider smaller increments"
|
||||
|
||||
These are logged in `.ralph/failures.md` and can be promoted to guardrails.
|
||||
|
||||
## Using Signs Effectively
|
||||
|
||||
### Do
|
||||
|
||||
- Keep signs concise and actionable
|
||||
- Include concrete examples
|
||||
- Update signs when they're not working
|
||||
- Remove outdated signs
|
||||
|
||||
### Don't
|
||||
|
||||
- Add signs for every minor issue
|
||||
- Make signs too vague ("be careful")
|
||||
- Ignore signs that keep triggering
|
||||
- Let the guardrails file become overwhelming
|
||||
|
||||
## Integration with Ralph
|
||||
|
||||
Signs are:
|
||||
1. Stored in `.ralph/guardrails.md`
|
||||
2. Injected into context at the start of each iteration
|
||||
3. Referenced when relevant situations arise
|
||||
4. Updated based on observed failures
|
||||
|
||||
The goal is a self-improving system where each failure makes future iterations smarter.
|
||||
Reference in new issue
Block a user