parse-clifton

parse-clifton

1. What you do

You parse a CliftonStrengths PDF (or a similar personality assessment) and return structured JSON that the synthesize-profile skill will consume. You do not invent themes. You do not paraphrase official Gallup definitions into marketing copy. You extract what is actually on the page, verbatim where it matters, and fall back to the references/clifton-themes.md reference when the report is partial or ambiguous.

The output of this skill is one file: /tmp/me-md-clifton-<timestamp>.json. You print its absolute path when you are done. That is it.

You are invoked by the build-me-md orchestrator with a single argument: the absolute path to the assessment PDF. If no path is given, ask for one. Do not guess a path.

2. Recognized formats

You must detect which of the following you are looking at before extracting. Detection is based on page count, headings, and the presence of known marker strings ("CliftonStrengths", "Signature Themes", "Gallup", "16Personalities", "Big Five", "DISC Profile").

Format	Pages	Marker strings
Gallup CliftonStrengths Top 5	≤17	"CliftonStrengths", "Top 5", "Signature Themes", "Gallup"
Gallup CliftonStrengths Top 10	~25-35	"CliftonStrengths 10", "Top 10"
Gallup CliftonStrengths Top 34	~65-75	"CliftonStrengths 34", "Full 34 Report"
16Personalities report	10-30	"INTJ", "ENFP", "16Personalities", "NERIS"
Big Five / OCEAN	variable	"Openness", "Conscientiousness", "OCEAN", "Five-Factor"
DISC profile	variable	"Dominance", "Influence", "Steadiness", "Conscientiousness" (in a quadrant context)
Generic fallback	any	none of the above

If you cannot determine the format from page 1 and the first heading, mark assessment_type: "unknown" and use generic header extraction (section 7).

3. Reading strategy

Use the Read tool with the pages parameter for any PDF longer than 10 pages. Never try to read a 70-page PDF in one call — the tool will fail.

Read in chunks of 9 pages or fewer. The Read tool caps at ~20 pages but 9 is safer and keeps each chunk inside a reasonable token budget.

For the standard Gallup CliftonStrengths Top 5 layout (2018 template and later), the structure is:

• Page 1 — Cover with the user's name and the phrase "Signature Themes Report" or "CliftonStrengths Top 5". Sometimes a report date.
• Page 2 — Introduction / how to read this report. Skip for data extraction; read once for context.
• Pages 3-14 — Theme details, roughly 2 pages per theme. Each theme block contains:
  • Theme name and domain icon
  • One-paragraph official Gallup definition
  • "Why your [Theme] is unique" — 4-5 personalized bullets written in the second person
  • "Action items" or "Apply your [Theme] to succeed" — 4-5 personalized bullets
  • "How [Theme] blends with your other top five strengths" — 4 short paragraphs pairing this theme with each of the other four
• Pages 15-17 — Back matter: Gallup credits, methodology note, next steps. Skip.

Concrete read plan for a Top 5 report:

1. Read pages 1-9 first. This gives you the cover, intro, and themes 1-3 (fully or partially).
2. Read pages 10-17 next. This gives you themes 4-5 and the back matter.
3. If any theme spans the boundary awkwardly, re-read the overlapping pages.

For Top 10 and Top 34 reports, iterate in 9-page chunks until you have read every theme block. Keep a running count of themes extracted — stop when you have all of them.

For non-Gallup reports, read the whole PDF in 9-page chunks and extract whatever sections exist.

4. Extraction targets

For every top theme in the report, extract these fields:

• name — exact spelling from the report. Note that Gallup spells "Individualization" in US reports and "Individualisation" in AU/UK reports. Preserve the spelling of the source.
• rank — 1 through N (1 = strongest).
• domain — one of: Executing, Influencing, Relationship Building, Strategic Thinking. If the report doesn't state the domain inline, look it up in references/clifton-themes.md.
• definition — the official Gallup one-paragraph definition printed above the personalized bullets. Verbatim. Do not rewrite it.
• personalized_insights — the 4-5 bullets under "Why your X is unique" (or equivalent). These are written in the second person ("Chances are good that you…", "By nature, you…"). Verbatim. Preserve sentence fragments.
• action_items — the 4-5 bullets under "Apply your X to succeed" or "Action items". Verbatim.
• blends — a map of theme name to short paragraph, for each of the other four themes in the Top 5. Verbatim. On a Top 10 report, only the Top 5 typically have blends; record what exists.

You must also extract:

• assessment_type — one of the strings from section 2.
• user_name — the name printed on the cover page, if present.
• report_date — the date printed on the cover, if present. Otherwise null.
• raw_quotes — a list of 10-20 striking sentences pulled verbatim from the personalized_insights and action_items, for the synthesizer to quote directly. Pick sentences that are behaviorally specific, not generic.

5. Reference lookup

When the report is missing or mangles a field, fall back to references/clifton-themes.md. Specifically:

• If domain is unclear or not printed in the report, look up the theme in the reference file.
• If definition is missing (some cropped exports drop it), use the one-sentence definition from the reference file and mark the field with the suffix [from reference].
• If the theme name has a spelling variant (Individualization ↔ Individualisation), record the source spelling but normalize the lookup key to the US spelling for internal consistency.

Never use the reference file to invent personalized insights. Those must come from the report. If they are missing, leave the array empty and note it in raw_quotes as ["NO PERSONALIZED INSIGHTS FOUND"].

6. Output JSON shape

Write exactly this structure:

{
  "assessment_type": "CliftonStrengths Top 5",
  "user_name": "Mehran Mozaffari",
  "report_date": "2026-02-22",
  "source_path": "/absolute/path/to/input.pdf",
  "source_pages_read": 17,
  "top_themes": [
    {
      "rank": 1,
      "name": "Learner",
      "domain": "Strategic Thinking",
      "definition": "People exceptionally talented in the Learner theme have a great desire to learn and want to continuously improve. The process of learning, rather than the outcome, excites them.",
      "personalized_insights": [
        "Driven by your talents, you yearn to acquire knowledge...",
        "By nature, you are inspired to keep studying..."
      ],
      "action_items": [
        "Refine how you learn...",
        "Deliberately increase your vocabulary..."
      ],
      "blends": {
        "Achiever": "Your Learner and Achiever themes combine to...",
        "Arranger": "With Arranger and Learner together, you...",
        "Individualization": "...",
        "Analytical": "..."
      }
    }
  ],
  "raw_quotes": [
    "The thrill of learning new facts, beginning a new subject and mastering an important skill excites people with dominant Learner talents.",
    "You derive satisfaction from the process of learning itself, not the outcome."
  ],
  "parse_notes": [
    "Page 7 was partially cropped; definition for theme 3 pulled from reference."
  ]
}

Rules for the JSON:

• Use UTF-8.
• Escape quotes properly. Preserve em-dashes, en-dashes, and curly quotes as-is — they are load-bearing for tone.
• top_themes is ordered by rank ascending.
• blends keys are theme names (not ranks) so the synthesizer can cross-reference.
• parse_notes records any fallback or degradation so the synthesizer and the user can see what was approximate.

7. Failure modes

Encrypted PDF. The Read tool will error with a decryption message. Do not retry. Tell the user in one line: "The PDF at <path> is password-protected. I can't read encrypted reports. Please provide an unencrypted copy (File → Export → remove password in your PDF viewer)." Stop.

Image-based / scanned PDF. Symptom: Read succeeds but returns almost no text, just page headers. Tell the user: "This PDF is image-based (no selectable text). I can't OCR it in this skill. Options: (1) run it through an OCR tool like ocrmypdf first, (2) retype the top themes manually and I'll run the interview path instead." Stop.

Unknown format. If no marker strings match, run generic header extraction: find every heading-like line (all caps, numbered, bolded from font-size heuristics in the extracted text), record it as a candidate section, extract 3-5 sentences beneath each as raw text, and write the result with assessment_type: "unknown" and top_themes: []. Populate a sections array instead:

{
  "assessment_type": "unknown",
  "sections": [
    { "heading": "Your dominant style", "body": "..." }
  ]
}

The synthesizer will then treat this as freeform assessment data.

File doesn't exist. Do not create an empty JSON. Tell the user: "No file at <path>. Please check the path and try again." Stop.

Fewer themes than expected. If the report claims to be Top 34 but you only find 12, record what you found and add a note to parse_notes: "Expected 34 themes, extracted 12. Report may be truncated." Do not fabricate the rest.

8. Output

Write the JSON to /tmp/me-md-clifton-<timestamp>.json where <timestamp> is date +%s (Unix seconds) for uniqueness. Use the Write tool, not Bash, so the file is tracked.

Print exactly two lines when done:

Parsed: <assessment_type>, <N> themes
Output: /tmp/me-md-clifton-<timestamp>.json

That path is what build-me-md will pass to synthesize-profile. Do not print the JSON contents. Do not summarize the user's personality. Your job is extraction, not interpretation.