povvo/claudikins-github-readme-for-perfectionists/think-tank

The Think-Tank

Goal: Extract high-converting patterns from similar tools and identify "Anti-Patterns" to avoid.

Step 1: Load Research Standards

Read the governance files:

1. references/scoring-rubric.md (How to grade quality).
2. references/badge-ecosystem.md (Which badges signal what).
3. references/gemini-deep-research.md (How to execute Gemini deep research).

Step 2: Define Search Criteria

Based on project context from codebase analysis, match on:

Search queries:

"best [project-type] [tech-stack] github"
"awesome [technology] list"
"[similar-tool] alternatives github"

Find 10-15 candidates, then narrow to top 5-7 based on stars and initial quality scan.

Step 2.5: Validation Methodology

Before accepting research findings, validate them.

Pre-Writing Research Phases

Validation Patterns

1. SMART Check: Is the claim Specific, Measurable, Achievable, Relevant, Time-bound?
2. Benchmark Comparison: Compare against industry/competitor/historical data
3. Evidence Requirement: Every claim needs supporting evidence
4. Run The Code: Test installation instructions, run examples yourself

Insight-to-Action Linking

Every research finding should connect to a README section:

Step 3: Score Each README

Rate each README 1-10 on these dimensions:

Quantitative Targets

The "Slop" Penalty

CRITICAL: Scan the text for the "Delve Index" (Delve, Seamless, Tapestry, Unleash, Landscape).

• Action: If _any_ appear in the Description/Intro, DEDUCT 2 POINTS.
• _Rationale:_ We do not want to mimic popular-but-lazy documentation.

Score Interpretation

Step 4: Pattern Extraction

For each high-scoring exemplar, extract:

Hero Section:

• Banner/logo style
• Tagline approach
• Badge selection and arrangement

Structure:

• Section order and naming conventions
• Use of collapsible sections
• Table of Contents style

Visuals:

• GIF usage (terminal recordings, UI demos)
• Diagram types (architecture, flow)
• Screenshot placement

Writing Style:

• Tone (minimal, conversational, opinionated, reference)
• Code example density
• Explanation depth

Step 5: Badge Recommendations

Badge Categories by Signal

Badge Styles

Pick ONE style across all badges:

• flat - Modern, clean (most projects)
• flat-square - Sharp edges (technical projects)
• for-the-badge - Large, bold (hero sections only)

Recommended Badge Sets

Minimal (3-4): Build Status, Version, License

Standard (5-6): Build Status, Coverage, Version, Downloads, License

Comprehensive (7 max): Build Status, Coverage, Quality, Version, Downloads, License, Last Commit

Badge Anti-Patterns

• Overload: 15+ badges creating visual chaos
• Inconsistent styling: Mix of flat, plastic, for-the-badge
• Vanity badges: "Made with JavaScript" adds no value
• Stale badges: Coverage showing 0% from broken CI
• Meaningless numbers: Badging 3 stars, 12 downloads

Step 6: Section Recommendations

Output Format

# Think-Tank Research Results
 
## Summary
 
-**Repos Analysed:** [X]
-**High Quality (8-10):** [X]
-**Key Patterns Identified:** [X]
 
## Top Exemplar: [Repo Name]
 
-**Score:** [X]/10 (Slop Penalty: [Yes/No])
-**Why it wins:** [specific reason]
-**Steal this:** [specific pattern]
 
## The Blueprint (Our Plan)
 
### 1. Visual Strategy
 
-**Hero:** [e.g., Terminal GIF using VHS]
-**Architecture:** [e.g., Mermaid Graph LR]
-**Density Target:** One visual every [X] words.
 
### 2. Badge Selection
 
_(Selected from references/badge-ecosystem.md)_
 
-[Badge 1]: [what it signals]
-[Badge 2]: [what it signals]
-[Badge 3]: [what it signals]
 
### 3. Structural Flow
 
1.Hero & Badges
2.Description (The Hook)
3.Quick Start (Time-to-Joy)
4....
 
### 4. Anti-Patterns to Avoid
 
-[Thing]: Common mistake seen in lower-rated READMEs

Handoff

Ask: "Research complete. We have the Badge list, Visual strategy, and Structural plan. Ready to wield the pen?"

• If refine -> more research
• If continue -> Use pen-wielding