Do you need analogies from history or arts?

Analogy Database Builder

Given a real-world situation the user wants analogies for, this workflow builds a comprehensive, scored database of historical events, literature, film, and TV that structurally parallel that situation. The database is iteratively expanded, quality-controlled, and output as self-contained HTML files.

I. Phase 1: Situation Analysis

1. Listen to the user describe the situation. Do not assume you know what elements matter. Ask clarifying questions if needed.

2. Identify the 3-7 core structural elements of the situation. These are the abstract dynamics — not the specific people or events, but the structural pattern. Examples of structural elements (these will be DIFFERENT for every project):

   • A power holder abusing authority
   • A perceived immunity or shield from consequences
   • An institutional investigation
   • A shift in power
   • A prosecution or accountability mechanism
   • A betrayal or defection from within
   • A coverup and its unraveling

3. Ask the user which element is MOST IMPORTANT. One element should carry the heaviest scoring weight. This determines what the database optimizes for.

4. Build the scoring rubric: Assign point values to each element totaling 100 points. The most important element gets the most weight (e.g., 25-30 points). Document:

   • Each element's name, definition, and max points
   • The minimum thresholds for inclusion (e.g., total ≥ 75, and minimum scores on critical elements)
   • What distinguishes a high score from a low score on each element

5. Identify penalty modifiers — structural disqualifiers that dock points regardless of base score. Common penalties include:

   • Tonal mismatch: Source is too childish, cartoonish, or tonally wrong for the situation
   • Inverted dynamic: The "prosecution" IS the evil act (the institution is the villain, not the target)
   • Corrupt agent: The entity doing the "good" thing is itself a bad actor (one villain destroying another, not genuine accountability)
   • Morally compromised protagonist: The hero figure is independently terrible outside the specific conflict
   • Alt-history: Source rewrites real events in ways that break the analogy

   CRITICAL DISTINCTION (The Bud Fox Rule): When applying "corrupt agent" or "morally compromised protagonist" penalties, distinguish between:

   • A minor participant who was corrupted by the villain and then cooperates with a legitimate authority → NO penalty
   • The prosecuting institution itself is corrupt or authoritarian → PENALTY
   • The protagonist is independently a terrible person outside of this specific conflict → PENALTY

6. Get user approval on the rubric before proceeding. Save the rubric as scoring_system.md in the project folder.

II. Phase 2: Initial Database Construction

7. Create the project folder per the user's file/folder policy. Initialize:

   • analogies.json — the master database
   • scoring_system.md — the rubric (from Phase 1)
   • README.md — project overview
   • build_html.py — HTML output generator
   • generate_histogram.py — distribution analysis generator

8. Sweep for candidates in batches of 15-25. For each batch:

   • Cast a WIDE net: history (ancient through modern), literature (classical through contemporary), film, TV, theater.
   • CRITICAL RESTRICTION 1 (No Hallucinations): NEVER use procedural generation scripts, AI hallucinations, or bulk variable swappers to lazily create entries. Every single candidate must represent a unique, authentic piece of real-world history, literature, or media.
   • CRITICAL RESTRICTION 2 (Analogy-Led, Not Source-Led Search): Do not select a show, movie, or book first and try to extract characters from it. The search must begin with the structural pattern itself. You must consider a vast array of different works and history across eras, selecting only the single most apt, high-fidelity analogy from any given source. The database must reflect a broad, diverse sweep of unique sources, not a clustered list of farmed characters from a few popular works.
   • For each candidate, map every structural element to specific content from the source
   • Score each element individually
   • Apply penalty modifiers where applicable
   • Write detailed explanation bullets explaining the scoring rationale
   • Mark entries as "included" or "excluded" based on thresholds
   • For excluded entries, document the specific reason for exclusion

9. Handle deduplication during evaluation:

   • If a candidate covers the same event/story as an existing entry, mark it as a deduplication
   • Do NOT give deduplication entries full scores — set their scores to 0 and status to "excluded"
   • NEVER use placeholder values (like "x") in element mappings for included entries

10. Run the FIRST batch through the evaluator script, immediately rebuild the HTML outputs, check the distribution, and STOP AND YIELD to ask the user for approval. This ensures the scoring logic and elements are properly matched before scaling up.

11. Once the user approves the first batch, automatically proceed to generate, process, and execute all subsequent batches sequentially until the target count is met. Do NOT ask for permission between subsequent batches. However, you MUST rebuild the HTML outputs and run the distribution check after EVERY single batch without fail.

III. Phase 3: Quality Control

12. Check decade/era distribution. The database MUST adhere to the following strict distribution ratios to prevent modern recency bias:

    • 2020-2025: 2.5
    • 2010-2020: 3
    • 2000-2010: 2
    • Each decade 1980-2000: 2
    • Each decade 1900-1980: 1
    • 1800-1900: 2
    • Each century 1000-1800: 1
    • Each century 500 BC to 1000: 0.5 If any modern era dramatically exceeds these mathematical targets relative to the older eras:
    • Identify the weakest/most redundant entries in that over-represented era
    • Demote them to "excluded" with a documented reason
    • Actively search for classical, historical, and literary candidates to balance the scale

13. Run a duplicate title check. Exact title matches should not exist — each entry must have a unique title.

14. Run a near-duplicate check. Sort all included entries by title alphabetically and look for:

    • Same event described under different titles (e.g., "The Conviction of X" and "The Prosecution of X")
    • Same source with minor title variations
    • When found, keep the better entry and exclude the weaker one
    • Exception: If two entries cover genuinely different aspects of the same event (e.g., the trial itself vs. a literary analysis of the trial), both can stay — but combine them if the distinction isn't meaningful

15. Audit for penalty violations. Sweep all included entries for:

    • Corrupt agent/institution violations that were missed
    • Morally compromised protagonists
    • Inverted dynamics (the "prosecution" IS the evil)
    • Apply penalties and re-evaluate inclusion status

16. Respond to user review feedback. When the user flags specific entries:

    • If they say an excluded entry should be included, re-score it with corrected reasoning and include it
    • If they say an included entry should be excluded, exclude it with their reasoning documented
    • Do not argue — the user's judgment on specific entries overrides the rubric

IV. Phase 4: Output Generation

17. Generate self-contained HTML output files from analogies.json. The HTML files must:

    • ALWAYS base their Python generation code and HTML/CSS styling strictly on apt_analogies_templates skill to guarantee visual consistency.
    • Embed all data directly (no fetch calls, no external dependencies)
    • Sort entries by score (highest first)
    • Display all element mappings and explanation bullets
    • For excluded entries, prominently display the exclusion reason
    • Be visually clean and scannable

18. Generate a distribution histogram showing the breakdown of included entries using the following strict logic:

    • CRITICAL RESTRICTION 3 (Always Output Histogram File): Every single time you generate or update the HTML files, you MUST simultaneously generate the histogram and literally save it to a physical file named histogram.md. Do not just print it to the terminal. Ensure the output is wrapped in a markdown text-block inside the .md file to preserve ASCII spacing.
    • ALWAYS base the Python generate_histogram.py script precisely on apt_analogies_templates skill.
    • This skill file guarantees consistent parsing of specific time era buckets and handles writing it to histogram.md.

19. Update scoring_system.md to reflect any penalties or rules added during the process (especially those added from user feedback).

20. Update README.md with final statistics, the sequence of events, and a file reference table.

V. Phase 5: Final Delivery

21. Present the user with:

    • Final counts (total evaluated, included, excluded)
    • The decade distribution histogram
    • The HTML files for review
    • A summary of any methodology changes made during the process

22. If the user spots issues during final review, fix them immediately and rebuild the HTML outputs.

VI. Key Principles

• The rubric is mathematical, not vibes-based. Every inclusion/exclusion must be traceable to specific element scores and thresholds.
• Analogy-Led, Not Source-Led (No Force-Fitting): Start with the target structural pattern, not a source. Only evaluate a work if it naturally contains a primary, high-fidelity match. Never mine a chosen book, show, or movie to force secondary/tertiary characters into the database.
• Excluded entries are not deleted. They go to a separate "graveyard" HTML file with documented reasons. This makes the methodology auditable.
• The user's judgment on specific entries overrides the rubric. If the user says "include this," include it. If they say "exclude this," exclude it. Then update the methodology to reflect their reasoning so future entries are scored consistently.
• Balance matters. A database that's 80% from one decade or 90% one medium is structurally weak regardless of individual entry quality.
• Documentation is critical. Someone opening the project folder later should be able to understand exactly how every entry was scored, why every exclusion was made, and what the methodology is.
• Batch processing is mandatory. Never try to evaluate 200 candidates in one pass. Process 15-25 at a time, rebuild outputs, check distribution, and iterate.

• 01_analogies_database.md — The complete list of analogies with their alignment grades.