beam-ai-team/generate-philosophy-doc

Generate Philosophy Document

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

Safety Contract

Before saving a philosophy document, show the domain, target audience, research sources, destination path, and overwrite risk. Require explicit user approval in the current turn before writing or overwriting local files. Researching sources, outlining the document, and drafting content in chat do not require approval.

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.