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:

• Foundational principles (research-backed)

• Frameworks and methodologies

• Anti-patterns dictionary

• Design checklists

• Case studies with metrics

• Measurement frameworks

• Academic and industry references

Workflow

Step 1: Define the Domain

Ask the user to specify:

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

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

Target audience: "Who will use this document?"

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

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:

Foundational Research (principles and theory):

• Search: "[domain] fundamental principles"

• Search: "[domain] research studies"

• Search: "[domain] psychology" or "[domain] user behavior"

Framework Research (methodologies):

• Search: "[domain] frameworks"

• Search: "[domain] best practices methodology"

• Search: "[domain] process workflow"

Anti-Pattern Research (common mistakes):

• Search: "[domain] common mistakes"

• Search: "[domain] anti-patterns"

• Search: "worst [domain] practices"

Metrics Research (measurement):

• Search: "[domain] KPIs metrics"

• Search: "[domain] benchmarking"

• Search: "[domain] success metrics"

Case Study Research (real examples):

• Search: "[domain] case studies"

• Search: "[domain] before after"

• Search: "[domain] success stories"

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:

• Name: Concise and memorable (e.g., "Mobile-First Design")

• Definition: Clear 1-sentence explanation

• Why This Works: Research-backed rationale

• Application: Wrong vs. Right examples (concrete)

• 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"):

• Framework name: Memorable and descriptive

• Visual diagram: ASCII art or description

• 3-5 phases: Sequential steps

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

• Name: Memorable (e.g., "The Wall of Text")

• Symptom: How to recognize

• Example: Concrete wrong example

• Why It Fails: Explanation with data

• Fix: How to correct

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

• Pre-Design Checklist: Before starting work

• Mid-Design Checklist: During execution

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

• Context: Background and situation

• Challenge: Problem to solve

• Approach: How principles were applied

• Before metrics: Quantified starting point

• After metrics: Quantified results

• Improvement: Percentage gains

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

• Tier 1: Critical metrics (make-or-break)

• Tier 2: Important metrics (quality indicators)

• Tier 3: Nice-to-have metrics (optimization)

• Red flags: When to take immediate action

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

• Academic Sources: Peer-reviewed research

• Industry Research: Authoritative reports

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

• Read full document - Check flow and coherence

• Validate against checklist - Ensure quality standards met

• Test with target audience (if possible) - Get feedback

• Refine based on feedback - Make improvements

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

• Standalone File: Save as [domain]-philosophy.md in appropriate location

• System Documentation: Place in 00-system/documentation/ if system-wide

• Project Documentation: Place in project folder if project-specific

• 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

Too Broad: Domain too general to be actionable

• Fix: Narrow scope to specific subdomain

Too Shallow: Research insufficient for depth

• Fix: Conduct more targeted searches, find academic sources

No Metrics: Principles lack quantified support

• Fix: Search for benchmarking data, case study metrics

Abstract Examples: Examples too generic to be useful

• Fix: Use real scenarios, specific companies/products

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:

• Comprehensive: Covers all 8 core sections with depth

• Research-Backed: Claims supported by citations and data

• Actionable: Readers can apply principles immediately

• Professional: Publication-ready quality

• Measurable: Success metrics clearly defined

• Validated: Passes quality checklist (80%+ grade)

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