# Quick Start Guide

Get started with the Cross-Iteration Pattern Synthesis System in 5 minutes.

## Prerequisites

```bash
# Install jq (JSON processor for validation)
sudo apt-get install jq     # Ubuntu/Debian
brew install jq             # macOS
choco install jq            # Windows
```

## Installation

```bash
# Clone this repository
git clone <repo-url> pattern-synthesis
cd pattern-synthesis

# Make validator executable
chmod +x validators/check_patterns.sh

# Verify installation
./validators/check_patterns.sh pattern_library_template.json
```

## First Generation (3 Minutes)

### Step 1: Start Claude Code

```bash
claude
```

### Step 2: Generate First 5 Iterations

```bash
/project:infinite-synthesis specs/example_spec.md output 5
```

**What happens**:
- Wave 1 generates 5 unique visualizations
- Pattern library automatically created
- Takes ~2-3 minutes

### Step 3: View Results

```bash
# Check generated files
ls output/
# Output: visualization_1.html ... visualization_5.html

# Check pattern library
cat pattern_library/patterns.json | jq '.patterns | keys'
# Output: ["structural", "content", "innovation", "quality"]
```

### Step 4: Validate Patterns

```bash
./validators/check_patterns.sh pattern_library/patterns.json
```

**Expected output**:
```
✓ Valid JSON
✓ All required fields present
✓ Pattern categories complete
Version: 1.0
Total patterns: 12
Quality score: 95% complete
```

## Second Generation (Pattern-Guided)

### Step 5: Generate 5 More Iterations

```bash
/project:infinite-synthesis specs/example_spec.md output 10
```

**What happens**:
- Wave 2 generates iterations 6-10
- Sub-agents receive pattern library as examples
- Quality improves (~15-20%)
- Pattern library updates to v1.1

### Step 6: Analyze Improvement

```bash
/project:analyze-patterns pattern_library/patterns.json output
```

**Expected results**:
```
Pattern Adoption Rate: 80%
Quality Improvement: +18%
Consistency Improvement: +42%
```

## View Your Visualizations

Open any generated HTML file in a browser:

```bash
# macOS
open output/visualization_6.html

# Linux
xdg-open output/visualization_6.html

# Windows
start output/visualization_6.html
```

Compare iteration 1 (no patterns) with iteration 6 (pattern-guided). Notice:
- More consistent code organization
- Better documentation
- Similar architectural patterns
- Still unique and creative!

## Next Steps

### Continue Generation

```bash
# Generate 10 more iterations (total: 20)
/project:infinite-synthesis specs/example_spec.md output 20
```

### Try Infinite Mode

```bash
# Continuous generation until context limit
/project:infinite-synthesis specs/example_spec.md output infinite
```

### Create Custom Specification

```bash
# Copy example spec
cp specs/example_spec.md specs/my_spec.md

# Edit with your requirements
nano specs/my_spec.md

# Generate from your spec
/project:infinite-synthesis specs/my_spec.md my_output 10
```

### View Pattern Details

```bash
# See all structural patterns
cat pattern_library/patterns.json | jq '.patterns.structural'

# View specific pattern
cat pattern_library/patterns.json | jq '.patterns.structural[0]'

# Check pattern adoption
cat pattern_library/patterns.json | jq '.metadata.avg_quality_score'
```

## Common Tasks

### Extract Patterns from Existing Code

```bash
# Analyze existing project
/project:extract-patterns /path/to/existing/code pattern_library/extracted.json

# Use those patterns for new generation
/project:infinite-synthesis specs/new_spec.md new_output 10 pattern_library/extracted.json
```

### Compare Pattern Libraries

```bash
# After generating 10 iterations
cp pattern_library/patterns.json pattern_library/wave2.json

# Generate 10 more (total: 20)
/project:infinite-synthesis specs/example_spec.md output 20

# Compare versions
diff <(jq '.patterns.structural' pattern_library/wave2.json) \
     <(jq '.patterns.structural' pattern_library/patterns.json)
```

### Validate Before Using

```bash
# Always validate pattern library before generation
./validators/check_patterns.sh pattern_library/patterns.json

# Fix any issues reported
# Then proceed with generation
```

## Troubleshooting

### Issue: "jq: command not found"

**Solution**: Install jq (see Prerequisites)

### Issue: Pattern library not being used

**Check**:
```bash
# Verify pattern library exists
test -f pattern_library/patterns.json && echo "Exists" || echo "Missing"

# Verify it's valid
./validators/check_patterns.sh pattern_library/patterns.json
```

**Solution**: Re-run pattern extraction
```bash
/project:extract-patterns output pattern_library/patterns.json
```

### Issue: Quality not improving

**Check**:
```bash
# View pattern count
cat pattern_library/patterns.json | jq '.patterns.structural | length'
# Should be 3-5

# Check for success metrics
cat pattern_library/patterns.json | jq '.patterns.structural[0].success_metrics'
# Should not be empty
```

**Solution**: Re-extract with deep analysis
```bash
/project:extract-patterns output pattern_library/patterns.json deep
```

### Issue: Iterations too similar

**Solution**: Emphasize uniqueness in spec

Edit your spec file to add:
```markdown
## Uniqueness Requirements (CRITICAL)

Each iteration MUST differ in:
1. Data domain (different subject matter)
2. Visualization type (different chart type)
3. Visual style (different colors, layout)
4. Interaction model (different user interactions)
5. Technical approach (different implementation)

Similarity > 50% to any existing iteration = FAILURE
```

## Understanding the Output

### Iteration Files

```html
<!-- Each iteration is a self-contained HTML file -->
<!DOCTYPE html>
<html>
<head>
  <title>Visualization Title</title>
  <!-- Embedded CSS -->
  <style>...</style>
</head>
<body>
  <!-- Visualization content -->
  <div id="container"></div>

  <!-- Embedded JavaScript -->
  <script>
    // Notice patterns from pattern library:
    // - Modular structure (data/view/controller)
    // - Progressive documentation
    // - Defensive error handling
    // - Novel innovation unique to this iteration
  </script>
</body>
</html>
```

### Pattern Library Structure

```json
{
  "version": "1.1",
  "patterns": {
    "structural": [
      {
        "name": "Pattern name",
        "description": "What it does",
        "example_file": "output/visualization_3.html",
        "key_characteristics": ["trait1", "trait2"],
        "success_metrics": "Why it works",
        "code_snippet": "// Example code..."
      }
    ]
  }
}
```

### Analysis Report

```markdown
# Pattern Library Effectiveness Report

## Key Findings
- Pattern Adoption: 80% (8/10 iterations use patterns)
- Quality Improvement: +18%
- Consistency: Variance reduced 42%

## Top Patterns
1. Modular Three-Layer Architecture (80% adoption)
2. Progressive Disclosure Documentation (60% adoption)
3. Guard Clause Error Handling (50% adoption)
```

## Tips for Success

### 1. Start Small
Begin with 5-10 iterations to establish patterns before scaling up.

### 2. Validate Early
Run the validator after first pattern extraction to catch issues early.

### 3. Review Patterns
Look at extracted patterns to understand what the system learned:
```bash
cat pattern_library/patterns.json | jq '.patterns.structural[0]' | less
```

### 4. Iterate on Specs
If patterns aren't what you want, refine your specification and regenerate.

### 5. Monitor Quality
Use the analysis command to track improvement:
```bash
/project:analyze-patterns pattern_library/patterns.json output
```

### 6. Preserve Innovation
If iterations become too similar, reduce pattern count:
```bash
# Use "quick" mode for 3 patterns per category instead of 5
/project:extract-patterns output pattern_library/patterns.json quick
```

## Example Session

Here's a complete session from start to finish:

```bash
# Session start
claude

# Generate Wave 1 (cold start)
/project:infinite-synthesis specs/example_spec.md viz 5
# → Creates viz/visualization_1.html through visualization_5.html
# → Creates pattern_library/patterns.json v1.0

# Validate patterns
./validators/check_patterns.sh pattern_library/patterns.json
# → ✓ Valid JSON, 12 patterns extracted

# Review extracted patterns
cat pattern_library/patterns.json | jq '.patterns.structural[0].name'
# → "Modular Three-Layer Architecture"

# Generate Wave 2 (pattern-guided)
/project:infinite-synthesis specs/example_spec.md viz 10
# → Creates visualization_6.html through visualization_10.html
# → Updates pattern_library/patterns.json to v1.1

# Analyze effectiveness
/project:analyze-patterns pattern_library/patterns.json viz
# → Pattern Adoption: 80%
# → Quality Improvement: +18%

# View a visualization
open viz/visualization_7.html

# Continue with Wave 3
/project:infinite-synthesis specs/example_spec.md viz 15
# → visualization_11.html through visualization_15.html
# → pattern_library/patterns.json v1.2

# Final analysis
/project:analyze-patterns pattern_library/patterns.json viz
# → Pattern Adoption: 90%
# → Quality Improvement: +22%
# → Consistency: Variance reduced 58%

# Success! 15 high-quality visualizations with consistent patterns
```

## What's Next?

### Learn More
- Read [README.md](README.md) for comprehensive overview
- Read [EXAMPLES.md](EXAMPLES.md) for real-world use cases
- Read [ARCHITECTURE.md](ARCHITECTURE.md) for technical details

### Customize
- Edit `specs/example_spec.md` to create custom specifications
- Modify `pattern_library_template.json` to add new pattern categories
- Extend `.claude/commands/` for custom workflows

### Share
- Export your pattern library: `cp pattern_library/patterns.json my_patterns.json`
- Share with team: Pattern libraries are reusable across projects
- Contribute: Add your patterns to community collections

## Getting Help

### Check Documentation
- **README.md**: Overview and features
- **EXAMPLES.md**: Real-world examples
- **ARCHITECTURE.md**: Technical deep dive
- **CLAUDE.md**: Agent instructions (for Claude Code)

### Common Questions

**Q: How many iterations before patterns emerge?**
A: Typically 5-10 iterations. Quality improvement visible after 10-15.

**Q: Can I use my own pattern library?**
A: Yes! Extract from any codebase or manually create one.

**Q: Will patterns reduce creativity?**
A: No. Patterns provide foundation. Innovation metrics show creativity remains high.

**Q: How do I stop infinite mode?**
A: It stops automatically at 80% context budget or when quality plateaus.

**Q: Can I edit patterns manually?**
A: Yes. Edit the JSON, then validate with `check_patterns.sh`.

## Success Criteria

You're successful when you see:

✓ Pattern adoption rate >70%
✓ Quality improvement >15%
✓ Consistency improvement >40%
✓ Innovation preservation (still unique iterations)
✓ Pattern library validates without errors
✓ Generated output meets your spec requirements

Congratulations! You're now using cumulative learning to generate progressively better iterations.

---

**Time to first results**: 3 minutes
**Time to see improvement**: 5 minutes
**Time to mastery**: 30 minutes

Start now: `/project:infinite-synthesis specs/example_spec.md output 5`