Skills
skills/abdullahbeam/nexus-design-abdullah/generate-philosophy-doc

generate-philosophy-doc

SKILL.md

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:

Example Philosophy Document:

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.

Weekly Installs
14
Repository
abdullahbeam/ne…abdullah
GitHub Stars
2
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn
Installed on
codex12
gemini-cli12
opencode12
claude-code11
github-copilot9
cursor9