structural-review
$
npx mdskill add lyndonkl/claude/structural-reviewDiagnoses macro-structure flaws in essay drafts before voice edits.
- Fixes meandering arguments and buried topic sentences.
- Depends on paragraph extraction and outline generation.
- Flags structural blockers with tiered severity ratings.
- Outputs Argument flow and Structural blockers sections.
SKILL.md
.github/skills/structural-reviewView on GitHub ↗
---
name: structural-review
description: Performs pass-1 structural review of a substacker essay draft — argument flow, out-of-order moves, buried topic sentences, missing pivots, weak signposting, paragraph-logic issues. Emits the "Argument flow" and "Structural blockers" sections of the Editor artifact. Use when reviewing a draft's macro-structure before addressing voice, when a draft feels like it meanders, or when the user asks whether the argument lands. Trigger keywords: structure, argument flow, outline, signposting, meandering, pivot, macro edit, substantive edit.
---
# Structural Review
## Table of Contents
- [Workflow](#workflow)
- [Expected essay shape](#expected-essay-shape)
- [Worked example](#worked-example)
- [Guardrails](#guardrails)
**Related skills:** Called by the Editor as the first structural skill. Runs before voice-check, hedge-detector, slop-detector. Pairs with `paragraph-rhythm-check` (paragraph logic) and `opener-critique` / `closer-critique`.
## Workflow
```
Structural review of draft D:
- [ ] Step 1: Extract paragraphs as an array. For each: first-sentence topic + word count
- [ ] Step 2: Produce a 1-line-per-paragraph outline of the draft AS READ
- [ ] Step 3: Compare to expected essay shape (see below)
- [ ] Step 4: Flag out-of-order moves, buried topic sentences, walls, missing pivots, weak signposts
- [ ] Step 5: Per flag: tier (1 or 2), paragraph index, quote, reason, ≤2 suggested rewrites
```
## Expected essay shape
Writer's signature shape (from voice-profile signature moves + opening/closing patterns):
```
1. Confession / concrete admission (opener)
2. Reframe / thesis
3. Exposition (mechanism, data, arithmetic)
4. Pivot (usually a one-sentence paragraph)
5. Applied case / example (often the IPL/Kalshi trade or a pathology slide)
6. Bolded maxim or forward-looking close
```
Not every essay hits every beat — short reflective posts skip steps 3 and 5. Series-log posts compress 2-3 and always include a scoreboard in 6.
**Flag if**:
- Hook is news-based or generic-opener (see `opener-critique`).
- Step 3 (mechanism) appears before step 1 (confession). "In this post we'll explore" structure = tier-1.
- Step 5 is missing in a full essay (not a series-log). Writer's voice has lived texture; its absence is a signal.
- Step 6 is absent entirely (no close). Tier-1.
- Buried topic sentence: the paragraph's point is in sentence 3 or later. Flag as tier-2.
- Wall: paragraph >120 words with no internal pivot. Flag as tier-2.
## Worked example
**Draft outline (as Editor reads it)**:
- Para 1 (42 w): "In today's AI landscape, teams often wonder whether RAG or fine-tuning…"
- Para 2 (81 w): Defines RAG.
- Para 3 (68 w): Defines fine-tuning.
- Para 4 (bullets): Comparison list.
- Para 5 (55 w): "I think RAG is the right choice for most teams."
- Para 6 (37 w): "To summarize, both have merit."
**Flags (structural)**:
1. (Tier-1) Hook is generic ("In today's AI landscape…"). Expected: confession. Rewrites: (a) "I spent four months moving a RAG pipeline to a fine-tune. I was wrong about which would win." (b) "I had never shipped a fine-tune until last quarter."
2. (Tier-1) Mechanism before confession. Structural ordering violates the writer's shape. Rewrite: restructure so confession precedes exposition.
3. (Tier-1) No pivot paragraph. Suggest: insert one-sentence paragraph at ~paragraph 3.5 marking the turn.
4. (Tier-1) Argument runs through a bulleted list (para 4). Rewrite: convert to 3 short paragraphs, one mechanism each.
5. (Tier-2) Closer is "To summarize" — prompt residue + no bolded maxim. Rewrite: replace with a mechanism close (e.g., "**You're choosing where your domain knowledge lives — in weights, or in retrieval.**").
## Guardrails
1. Never flag voice issues. This skill is structural only.
2. Never propose more than 2 rewrite options per flag.
3. Flags are located by paragraph index. If the writer paginates sections, cite section + paragraph.
4. Do not rewrite the draft. Rewrites are ≤2 sentences each, bracketed.
5. Series posts (frontmatter `series: {slug}`) get a special-case: step 5 often IS the scoreboard+trade narration, not an extended applied case. Don't flag absence.
6. If the draft is a how-to / methodology post (H2 headers throughout, numbered steps), the expected shape is different (intro → sections → wrap). Detect and adapt.
## Quick reference
- Input: draft markdown.
- Output: the "Structural pass → Argument flow" + "Structural blockers" sections.
- Runs first in the Editor pipeline.
More from lyndonkl/claude
- abstraction-concrete-examplesBuilds structured abstraction ladders that translate high-level principles into concrete, actionable examples across 3-5 levels. Bridges communication gaps, reveals hidden assumptions, and tests whether abstract ideas work in practice. Use when explaining concepts at different expertise levels, moving between abstract principles and concrete implementation, identifying edge cases by testing ideas against scenarios, designing layered documentation, decomposing complex problems into actionable steps, or bridging strategy-execution gaps.
- academic-letter-architectGuides the creation of evidence-based academic recommendation letters, reference letters, and award nominations that combine concrete examples, meaningful comparisons, and genuine enthusiasm. Use when writing recommendation letters for students, postdocs, or colleagues, or when user mentions recommendation letter, reference, nomination, letter of support, endorsement, or needs help with strong advocacy and comparative statements.
- adr-architectureDocuments significant architectural and technical decisions with full context, alternatives considered, trade-offs analyzed, and consequences understood. Creates a decision trail that helps teams understand why decisions were made. Use when choosing between technology options, making infrastructure decisions, establishing standards, migrating systems, or when user mentions ADR, architecture decision, technical decision record, or decision documentation.
- adverse-selection-priorProduces a Bayesian prior probability that an offered transaction is +EV for the recipient, given that the counterparty chose to propose it. Applies Akerlof market-for-lemons logic -- if they offered it, they believe it is +EV for them, so the prior that it is +EV for us is materially below 50%. Reusable across trade evaluation, waiver drops (another team dropping a player is also adverse selection), job-offer analysis, M&A, and any "someone offered me this" situation. Use when you receive an unsolicited trade/offer/proposal, analyzing incoming trade prior, evaluating why a counterparty proposed a deal, or when user mentions adverse selection, market for lemons, why did they offer this, incoming trade prior, they proposed it, Bayesian adjustment on received offer.
- alignment-values-north-starCreates actionable alignment frameworks that give teams a shared North Star (direction), values (guardrails), and decision tenets (behavioral standards). Enables autonomous decision-making while maintaining organizational coherence. Use when starting new teams, scaling organizations, defining culture, establishing product vision, resolving misalignment, creating strategic clarity, or when user mentions North Star, team values, mission, principles, guardrails, decision framework, or cultural alignment.
- analogy-weight-checkFor every analogy in a substacker draft, verifies it carries mechanical weight — the analogy does real work explaining the mechanism, not merely decorates it. Cross-references analogy-catalog.md for novelty (is this analogy reused from a prior post?) and domain fit (biology > organizational > sports preferred; physics/military disfavored). Use whenever an analogy appears in the draft. Trigger keywords: analogy weight, decorative, mechanical weight, reused analogy, catalog check, metaphor check.
- answer-uncomfortable-questionTakes one strategic question about substacker ("should we launch paid?", "is this section dead?", "are we writing for the wrong audience?") and produces the mandatory evidence + reasoning + downside triad plus a recommendation. Used 3 times per Growth Strategist review. Trigger keywords: uncomfortable question, strategic question, evidence reasoning downside, triad.
- attribute-performanceFor each substacker post that materially over- or under-performs the rolling baseline (|z| ≥ 1.0), produces a plain-English attribution paragraph with calibrated confidence (high / medium / low / unexplained). Considers subject-line effect, topic zeitgeist, external share, day-of-week, length effect, and audience-notes signals. Labels unexplained outliers explicitly rather than fabricating a story. Use after compute-baseline when outlier posts exist. Trigger keywords: attribution, why did this post work, outlier explanation, performance analysis.
- auction-first-price-shadingComputes the optimal shaded bid for a first-price sealed-bid auction given a true private value, an estimate of the number of competing bidders N, and a value-distribution assumption. Implements the `(N-1)/N` equilibrium shading rule for uniform private values, adjusts for log-normal or empirical value distributions, layers a risk-aversion adjustment, and caps output against the bidder's remaining budget. Domain-neutral auction theory reusable across fantasy sports (baseball FAAB, NBA/NHL waiver auctions), prediction-market limit sizing, sealed procurement bids, and any blind-bid context. Use when user mentions "first-price auction bid", "sealed bid shading", "(N-1)/N", "FAAB bid amount", "auction shading", "optimal bid first-price", "bid for sealed-bid", "blind bid sizing", or when downstream logic needs a principled shade factor rather than an ad-hoc heuristic.
- auction-winners-curse-haircutApplies a Bayesian haircut to a bid valuation for common-value auctions where winning is itself evidence the bidder over-estimated. Takes a raw valuation, a value-type classification (common_value / private_value / mixed), the number of informed bidders N, and a signal-dispersion estimate, and returns an adjusted valuation. Domain-neutral and reusable across fantasy FAAB, prediction markets, M&A bids, ad-auction budgets, and any generic bidding context. Use when user mentions "winner's curse", "common value auction", "valuation haircut", "adverse valuation", "Bayesian bid adjustment", or "over-paying in auction".