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:

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

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. •Project Documentation: Place in project folder if project-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.