Each article type ("profile") activates a different subset of the rules with its own severity level. The table below is the primary reference. The order of priority for magazine / blog work is: fail rules first, then warn rules in roughly the order shown in CHECKLIST.md.
For non-magazine profiles see out-of-scope.md for the rules that exist in the CLI but were not extracted into agent-readable form.
| Rule | Severity | Notes |
|---|---|---|
engagement/DF-040-opening-hook |
FAIL | Required in first 200 words |
engagement/DF-042-concrete-examples |
FAIL | Every conceptual H2 |
visuals/DF-058-image-alt-text |
FAIL | All images |
visuals/DF-059-image-paths-resolve |
FAIL | All relative paths |
engagement/DF-041-question-before-answer |
warn | H2 openings |
engagement/DF-043-no-placeholder-names |
warn | No foo/bar in code |
engagement/DF-045-next-steps |
warn | Forward-linking section |
engagement/DF-046-section-transitions |
warn | At least 50% bridged |
engagement/DF-047-narrative-arc |
warn | Setup→confrontation→resolution |
voice/DF-052-active-voice |
warn | Passive ≤ 20% |
voice/DF-053-reader-focus-you |
warn | "you" ≥ ½ system phrases |
llm-artifacts/contractions |
warn | All forms contracted |
voice/DF-055-frontload-topic-sentence |
warn | Keyword in sentence 1 |
cognitive-load/DF-030-paragraph-length |
warn | ≤ 5 sentences |
cognitive-load/DF-031-list-length-max |
warn | ≤ 7 items |
cognitive-load/DF-032-list-length-min |
warn | ≥ 3 items |
cognitive-load/DF-033-section-density |
warn | ≤ 500 words |
readability/DF-050-flesch-kincaid |
warn | Grade ≤ 8 |
readability/DF-051-sentence-length |
warn | ≤ 30 words |
readability/DF-054-descriptive-headings |
warn | No bare "Overview" etc. |
visuals/DF-056-visual-support-density |
warn | Diagram for structure / density |
llm-artifacts/overused-words |
warn | 50+ word kill list |
llm-artifacts/filler-phrases |
warn | 20+ phrase kill list |
llm-artifacts/typographic-artifacts |
warn | Em dash / smart quote / emoji |
llm-artifacts/conjunctive-adverb-openers |
warn | No "Furthermore," at sentence start |
The composite framework blog/blog-engagement-framework.md passes when all eight of its sub-requirements pass. See that file for the orchestration.
The five-dimension engagement score (computed by docflow metrics and src/scoring/engagement.ts) maps to these rules:
| Dimension | Weight | Feeds from |
|---|---|---|
| Curiosity | 25% | DF-040 hooks, DF-041 question framing |
| Clarity | 25% | DF-050 FK grade, DF-051 sentence length, DF-054 heading descriptiveness |
| Action | 20% | DF-042 examples, code blocks |
| Flow | 15% | DF-046 transitions, DF-045 next steps, DF-047 arc |
| Voice | 15% | DF-053 reader focus, DF-052 active voice, voice score |
Target for publication: 90+ in each dimension. The score is informational; the gates that block publication are the FAIL rules in the matrix above.
| Profile | Notes |
|---|---|
| tutorial | Adds Gagné checklist, worked-example-before-exercise, step numbering, narrative arc as FAIL. See out-of-scope.md. |
| reference | Skips hooks, narrative arc, exercises, question-before-answer. FK grade 10. |
| whitepaper | FK grade 12. Passive ratio relaxed to 35%. Reader pronoun ratio not checked. Adds ethos-signal requirement. |
| book-chapter | FK grade 10. Passive ratio relaxed to 25%. Reader pronoun ratio not checked. Section density extended to 750 words. |
For the canonical per-profile FAIL/WARN list, see src/validators/profiles.ts.