11 KiB

Raw Blame History

Quick Start Guide

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

Prerequisites

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

Installation

# 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

claude

Step 2: Generate First 5 Iterations

/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

# 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

./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

/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

/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:

# 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

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

Try Infinite Mode

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

Create Custom Specification

# 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

# 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

# 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

# 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

# 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:

# 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

/project:extract-patterns output pattern_library/patterns.json

Issue: Quality not improving

Check:

# 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

/project:extract-patterns output pattern_library/patterns.json deep

Issue: Iterations too similar

Solution: Emphasize uniqueness in spec

Edit your spec file to add:

## 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

<!-- 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

{
  "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

# 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:

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:

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

6. Preserve Innovation

If iterations become too similar, reduce pattern count:

# 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:

# 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 for comprehensive overview
Read EXAMPLES.md for real-world use cases
Read 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

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

11 KiB Raw Blame History