beam-ai-team/generate-philosophy-doc

Generate Philosophy Document

Create comprehensive, research-backed philosophy and standards documents for any domain.

What This Skill Does

This skill generates high-quality philosophy documents similar to ux-onboarding-philosophy.md for any domain:

• UX & Design: Interface design, mobile UX, accessibility standards
• Marketing: Landing pages, email outbound, conversion optimization
• Technical: API design, architecture patterns, code standards
• Business: Sales processes, customer success, operations

Each document includes:

1. Foundational principles (research-backed)
2. Frameworks and methodologies
3. Anti-patterns dictionary
4. Design checklists
5. Case studies with metrics
6. Measurement frameworks
7. Academic and industry references

Workflow

Step 1: Define the Domain

Ask the user to specify:

1. Domain name: "What domain do you want to document?"

   • Examples: "Landing Page Design", "API Design Standards", "Email Outbound Best Practices"

2. Target audience: "Who will use this document?"

   • Examples: "UX designers", "Backend developers", "Marketing team"

3. Focus areas (optional): "Any specific areas to emphasize?"

   • Examples: "Conversion optimization", "Performance", "Accessibility"

Clarify scope: Ensure domain is specific enough to be actionable but broad enough to be useful.

---

Step 2: Conduct Research

Use the WebSearch tool or Perplexity API to gather comprehensive research:

Research Strategy:

1. Foundational Research (principles and theory):

   • Search: "[domain] fundamental principles"
   • Search: "[domain] research studies"
   • Search: "[domain] psychology" or "[domain] user behavior"

2. Framework Research (methodologies):

   • Search: "[domain] frameworks"
   • Search: "[domain] best practices methodology"
   • Search: "[domain] process workflow"

3. Anti-Pattern Research (common mistakes):

   • Search: "[domain] common mistakes"
   • Search: "[domain] anti-patterns"
   • Search: "worst [domain] practices"

4. Metrics Research (measurement):

   • Search: "[domain] KPIs metrics"
   • Search: "[domain] benchmarking"
   • Search: "[domain] success metrics"

5. Case Study Research (real examples):

   • Search: "[domain] case studies"
   • Search: "[domain] before after"
   • Search: "[domain] success stories"

6. Academic Research (credible sources):

   • Search: "[domain] academic research"
   • Search: "[domain] peer reviewed studies"

Execute 10-15 targeted searches covering all research areas. Synthesize findings into structured notes organized by section.

Optional: Use scripts/research_topic.py to generate search queries:

uv run python scripts/research_topic.py "Landing Page Design" "principles,frameworks,anti-patterns,metrics"

---

Step 3: Generate Document Structure

Use the bundled template to create the document structure:

Option A: Manual Creation

Copy assets/philosophy-template.md and fill in sections with research findings.

Option B: Script-Assisted

uv run python scripts/generate_structure.py "Landing Page Design" > output.md

Then fill in placeholders with researched content.

---

Step 4: Fill in Sections

Work through each section systematically. See references/document-template.md for detailed guidance on each section.

4.1 Executive Summary

• Core philosophy: Distill into 1 sentence
• The problem: What challenge does this solve?
• The solution: What approach does this recommend?
• Proof: Cite key research or metrics

Length: 100-200 words

---

4.2 Foundational Principles

Create 5-8 principles. Each principle needs:

1. Name: Concise and memorable (e.g., "Mobile-First Design")
2. Definition: Clear 1-sentence explanation
3. Why This Works: Research-backed rationale
4. Application: Wrong vs. Right examples (concrete)
5. Test: How to verify adherence

Format Pattern:

### Principle 1: [Name]

**Definition**: [One sentence]

**Why This Works**: [Research explanation with citation]

**Application**:
- WRONG: [Concrete bad example]
- RIGHT: [Concrete good example]

**Test**: [Verification method]

Quality Check:

• Examples must be concrete (not abstract)
• Research must be cited
• Tests must be practical

Length: 400-800 words total (80-160 per principle)

---

4.3 Framework & Methodology

Create a named framework (e.g., "LIFT Framework", "AIDA Model"):

1. Framework name: Memorable and descriptive
2. Visual diagram: ASCII art or description
3. 3-5 phases: Sequential steps
4. Each phase includes:
   • Purpose statement
   • Key activities (3-5 items)
   • Quality checklist (3-5 checkboxes)
   • Time budget (percentage)

Example Structure:

### The CLEAR Framework

[ASCII diagram showing 5 phases]

#### Phase 1: Capture Attention

**Purpose**: Hook user in first 3 seconds

**Key Activities**:
- Design hero section with compelling headline
- Use high-contrast CTA button
- Optimize above-fold content

**Quality Checklist**:
- [ ] Headline clearly states value proposition
- [ ] CTA visible without scrolling
- [ ] Hero image supports message

**Time Budget**: 20% of design process

Length: 400-600 words

---

4.4 Anti-Patterns Dictionary

Document 5-10 common mistakes:

1. Name: Memorable (e.g., "The Wall of Text")
2. Symptom: How to recognize
3. Example: Concrete wrong example
4. Why It Fails: Explanation with data
5. Fix: How to correct
6. Metrics: Impact data (if available)

Format:

### Anti-Pattern 1: "The Wall of Text"

**Symptom**: Landing page with 500+ words above fold, no visual breaks

**Example**:
WRONG:
[Paste or describe actual bad example]

**Why It Fails**: Users scan, don't read. Average time on page: 8 seconds.
Wall of text = 90% bounce rate (Source: Nielsen Norman Group)

**Fix**: Break into scannable sections with headers, bullets, and whitespace

**Metrics**: Before: 90% bounce | After: 45% bounce (50% improvement)

Length: 400-600 words total (60-80 per anti-pattern)

---

4.5 Design Checklists

Create 3 checklists:

1. Pre-Design Checklist: Before starting work
2. Mid-Design Checklist: During execution
3. Post-Design Checklist: Before launch

Format:

### Pre-Design Checklist

**Define Success Criteria**:
- [ ] Primary conversion goal defined
- [ ] Target audience identified
- [ ] Success metrics established

**Audience Analysis**:
- [ ] User personas documented
- [ ] Pain points identified
- [ ] Value proposition clear

Quality Standards:

• All items binary (yes/no)
• Specific and measurable
• No ambiguous language
• 3-5 items per category
• Can complete in <10 minutes

Length: 200-400 words

---

4.6 Case Studies

Include 2-3 real examples:

1. Context: Background and situation
2. Challenge: Problem to solve
3. Approach: How principles were applied
4. Before metrics: Quantified starting point
5. After metrics: Quantified results
6. Improvement: Percentage gains
7. Key insights: Learnings (3-5 bullets)

Example:

### Case Study: Dropbox Homepage Redesign

**Context**: Dropbox needed to improve conversion on homepage (2017)

**Challenge**: 65% bounce rate, unclear value proposition

**Approach**: Applied "Show Don't Tell" principle - replaced feature list
with video demo showing product in action

**Before**:
- Bounce Rate: 65%
- Sign-up Conversion: 2.8%
- Time on Page: 12 seconds

**After**:
- Bounce Rate: 42% (35% improvement)
- Sign-up Conversion: 4.2% (50% improvement)
- Time on Page: 48 seconds (300% improvement)

**Key Insights**:
- Video demo increased engagement 4x
- Visual demonstration beats text explanation
- Clear CTA after video critical for conversion

Length: 300-500 words total (150-250 per case study)

---

4.7 Measurement Framework

Create tiered metrics structure:

1. Tier 1: Critical metrics (make-or-break)
2. Tier 2: Important metrics (quality indicators)
3. Tier 3: Nice-to-have metrics (optimization)
4. Red flags: When to take immediate action
5. Measurement methods: How to collect data

Format:

### Success Metrics Hierarchy

TIER 1: CRITICAL METRICS (Make or Break)
  - Conversion Rate: Primary goal completion
    Target: >5% | Baseline: 2-3%

  - Bounce Rate: User engagement
    Target: <40% | Baseline: 50-60%

### Red Flags

CRITICAL RED FLAGS:

1. Conversion Rate < 2%
   -> Poor value proposition - Redesign messaging

2. Bounce Rate > 70%
   -> No engagement - Rethink content strategy

Length: 300-400 words

---

4.8 Research References

Organize sources by category:

1. Academic Sources: Peer-reviewed research
2. Industry Research: Authoritative reports
3. Best Practice Documentation: Standards and guides

Format:

### Academic Sources

1. **Cognitive Psychology**:
   - Nielsen, J. (2006). "F-Shaped Pattern For Reading Web Content"
   - Kahneman, D. (2011). "Thinking, Fast and Slow"

### Industry Research

1. **ConversionXL**: Landing page optimization studies
2. **Baymard Institute**: UX research and benchmarks

Quality Standards:

• Sources are authoritative
• Citations are complete
• Mix of academic and practical
• Recent (within 5-10 years preferred)

Length: 100-200 words

---

Step 5: Quality Validation

Use references/quality-checklist.md to validate the document:

Critical Checks:

• [ ] All 8 core sections present
• [ ] No placeholder text remains ([TODO], [PLACEHOLDER])
• [ ] 5-8 principles included
• [ ] 5-10 anti-patterns documented
• [ ] 2-3 case studies with metrics
• [ ] Research references cited
• [ ] Total length: 1,500-3,000 words

Content Quality:

• [ ] Examples are concrete (not abstract)
• [ ] Research is cited properly
• [ ] Metrics are specific
• [ ] Checklists are actionable
• [ ] Language is clear and professional

Formatting Quality:

• [ ] Markdown formatting correct
• [ ] Links work (TOC, cross-references)
• [ ] Headers hierarchical
• [ ] Visual hierarchy clear

Target Grade: B (80%+) minimum, A (90%+) recommended

---

Step 6: Iterate and Refine

After initial draft:

1. Read full document - Check flow and coherence
2. Validate against checklist - Ensure quality standards met
3. Test with target audience (if possible) - Get feedback
4. Refine based on feedback - Make improvements
5. Final proofread - Catch typos and errors

Common Refinements:

• Strengthen weak examples with more concrete details
• Add missing citations
• Improve clarity of complex explanations
• Enhance visual hierarchy with better formatting
• Cut redundant content

---

Step 7: Deliver Document

Output Format Options:

1. Standalone File: Save as [domain]-philosophy.md in appropriate location
2. System Documentation: Place in 00-system/documentation/ if system-wide
3. Build Documentation: Place in project folder if build-specific
4. External Sharing: Package with any additional context needed

Delivery Includes:

• Complete philosophy document
• Brief usage guide (how to apply)
• Quality checklist for future updates
• Recommendation for review timeline

---

Tips for Success

Research Quality

Do:

• Search multiple sources (10-15 queries minimum)
• Prioritize authoritative sources (academic, industry leaders)
• Look for quantified data and metrics
• Find real case studies with numbers
• Cross-reference claims across sources

Don't:

• Rely on single source
• Accept claims without evidence
• Use outdated research (>10 years old) without noting
• Include speculation without labeling it
• Cite non-authoritative sources

---

Writing Quality

Do:

• Use concrete examples (not abstract)
• Quantify whenever possible (X% improvement)
• Write in clear, professional tone
• Format for scannability (headers, lists, emphasis)
• Connect principles to research

Don't:

• Use jargon without definition
• Write long paragraphs (>4-5 lines)
• Make unsupported claims
• Use vague language ("might", "could", "maybe")
• Copy-paste without synthesis

---

Common Pitfalls

1. Too Broad: Domain too general to be actionable

   • Fix: Narrow scope to specific subdomain

2. Too Shallow: Research insufficient for depth

   • Fix: Conduct more targeted searches, find academic sources

3. No Metrics: Principles lack quantified support

   • Fix: Search for benchmarking data, case study metrics

4. Abstract Examples: Examples too generic to be useful

   • Fix: Use real scenarios, specific companies/products

5. Incomplete Sections: Missing key components

   • Fix: Use quality checklist, ensure all sections complete

---

Example Domains

UX & Design:

• Mobile App UX Design Philosophy
• Accessibility Standards Guide
• Visual Hierarchy Best Practices
• Micro-interaction Design Standards

Marketing:

• Landing Page Conversion Optimization
• Email Outbound Best Practices
• Cold Outreach Philosophy
• Content Marketing Standards

Technical:

• REST API Design Principles
• Microservices Architecture Standards
• Database Schema Design Philosophy
• Code Review Best Practices

Business:

• Sales Discovery Process Standards
• Customer Onboarding Philosophy
• Product Roadmap Planning Guide
• Remote Team Management Principles

---

References

Skill Resources:

• document-template.md - Detailed section guidelines
• quality-checklist.md - Validation checklist
• philosophy-template.md - Blank template

Example Philosophy Document:

• ux-onboarding-philosophy.md - Reference example

Scripts:

• scripts/research_topic.py - Generate research queries
• scripts/generate_structure.py - Generate document structure

---

Success Criteria

A successful philosophy document:

1. Comprehensive: Covers all 8 core sections with depth
2. Research-Backed: Claims supported by citations and data
3. Actionable: Readers can apply principles immediately
4. Professional: Publication-ready quality
5. Measurable: Success metrics clearly defined
6. Validated: Passes quality checklist (80%+ grade)

Target: Create documents that become authoritative references for the domain.