| name | think-tank |
| description | Use when researching documentation patterns after brain-jam phase. Analyses exemplar READMEs from similar high-star repositories, scores against rubric, extracts patterns. |
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:
references/scoring-rubric.md (How to grade quality).references/badge-ecosystem.md (Which badges signal what).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:
| Criterion | How to Match |
|---|
| Category | Same project type (CLI, library, framework, API, etc.) |
| Tech Stack | Same or similar languages/frameworks |
| Ecosystem | Same package manager (npm, PyPI, Cargo) |
| Complexity | Similar scope (simple util vs enterprise tool) |
| Maturity | Established projects with proven documentation |
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
| Phase | Activities | Output |
|---|
| Define Scope | Establish parameters before research | Parameter block |
| Gather Context | Structured information capture | Context template |
| Multi-Source Triangulation | Check multiple sources | Source comparison |
| Validation | Test claims, run examples | Evidence notes |
Validation Patterns
- SMART Check: Is the claim Specific, Measurable, Achievable, Relevant, Time-bound?
- Benchmark Comparison: Compare against industry/competitor/historical data
- Evidence Requirement: Every claim needs supporting evidence
- Run The Code: Test installation instructions, run examples yourself
Insight-to-Action Linking
Every research finding should connect to a README section:
| Research Finding | Section It Informs |
|---|
| Target audience characteristics | "Who This Is For" section |
| Common user problems | "Features" framing |
| Competitor gaps | "Why This Project" positioning |
| User language patterns | Terminology choices |
| Installation friction points | Quick Start optimisation |
Step 3: Score Each README
Rate each README 1-10 on these dimensions:
| Dimension | Weight | What to Look For |
|---|
| Value Proposition | 20% | Problem and solution crystal clear in first paragraph |
| Time to Joy (TTJ) | 20% | Commands to first working result (target: 2-3) |
| Visual Quality | 15% | GIFs, diagrams, code blocks, dark mode support |
| Structure | 15% | Logical flow, scannable, TOC if >200 lines |
| SEO Signals | 10% | Keywords in title, semantic headers, topics tagged |
| Badge Quality | 10% | Informative badges, 5-7 max, consistent style |
| Maintenance Signals | 10% | Recent commits, active issues, working links |
Quantitative Targets
| Metric | Good | Red Flag |
|---|
| Flesch-Kincaid Grade | 8-10 | >12 (too complex) |
| TTJ (commands to result) | 2-3 | >5 |
| Visual Density | 1 per 300 words | >600 words without visual |
| Badge Count | 5-7 | >10 or 0 |
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
| Score | Assessment |
|---|
| 9-10 | Exemplary - study closely |
| 7-8 | High quality - good patterns |
| 5-6 | Average - selective borrowing |
| 3-4 | Below average - learn what not to do |
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
| Category | Signal | When to Use |
|---|
| Build Status | "Code compiles and tests pass" | Always |
| Code Coverage | "Maintainers care about testing" | If coverage >60% |
| Version | "This is a releasable product" | If published to registry |
| Social Proof | "Crowd has vetted this" | Only if numbers impress (5000+ stars) |
| License | "Legal to use in my project" | Always |
| Activity | "Project is alive" | Only if actively maintained |
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
| Section | When to Include |
|---|
| Quick Start | Always - first thing after hero |
| Installation | Always - multiple methods if applicable |
| Usage/Examples | Always - show, don't just tell |
| API Reference | Libraries and frameworks |
| Configuration | If configurable |
| Architecture | Complex projects with multiple components |
| Contributing | Open source projects seeking contributions |
| FAQ | If common questions exist |
| Troubleshooting | If known gotchas exist |
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
