docs: update HANDOFF.md — Expert tier complete (full editorial cycle)
Expert is now Done with 2 human editorial passes. Updated work queue, systematic fixes checklist (now 13 items), spell name / dimension cross-tier audit results, and 7 new lessons learned (19-25). Made-with: Cursor
This commit is contained in:
+97
-63
@@ -1,51 +1,65 @@
|
||||
# Agent Handoff — Lore Rewrites & Editorial Passes
|
||||
|
||||
> Updated 2026-04-17 after completing Grandmaster systematic editorial. Read QUICKSTART.md and SKILL.md first.
|
||||
> Updated 2026-04-17 after completing Expert tier (full editorial cycle). Read QUICKSTART.md and SKILL.md first.
|
||||
|
||||
## What was just completed
|
||||
|
||||
### Grandmaster tier — systematic editorial (4 Grandmaster)
|
||||
### Expert tier — full editorial cycle (2 Expert)
|
||||
|
||||
Applied full systematic fixes checklist to all 140 Grandmaster items. 69 SVGs modified across 7 flavors. All lore audited; no rewrites needed.
|
||||
110 items across 7 flavors. Lore rewrites, systematic fixes, two human editorial passes (text + PDF visual), all complete.
|
||||
|
||||
**Systematic fixes applied (69 SVGs touched):**
|
||||
**Lore rewrites (13 items):**
|
||||
- Magic (3): Manaloom Thread, Riftstep Charm, Spirit-Anchor Nail
|
||||
- Recovery (8): Breath-of-Balm, Hearth-in-a-Cup, Ironstitch Poultice, Knit-Bone Cordial, Muscle-Memory Draught, Tonic of Gentle Stamina, Venom-No-More Phial, Weaver's Restorative Thread
|
||||
- Stealth (1): Dust of Quiet Boards
|
||||
- Strike (1): Garrote of Soft Whispers
|
||||
|
||||
1. **Potion RAW cleanup (12 actual potions):** Removed "Action to drink." (7 potions) and "Single use." (12 potions) where implied by subhead. Kept "Action to drink or administer." on Phoenix Draft (meaningful choice), "Action to sip." on Breath of Warmth Flask, and "Bonus Action to drink." where it overrides default action cost.
|
||||
**Boilerplate closer replacements (2):** Spellguard Veil, Catstep Powder — "treat it as a dare" removed.
|
||||
|
||||
2. **Non-potion subhead corrections (4 items):** Items with subhead "potion" that aren't drunk — liquids in flasks that are thrown or applied need appropriate subheads, not "potion":
|
||||
- Thunderburst Phial: potion → `throwable (60')` (thrown area effect)
|
||||
- Widow's Kiss Tincture: potion → `consumable (apply)` (weapon coating)
|
||||
- Nightkey Serum: potion → `consumable (apply)` (coated on tools)
|
||||
- Limb-Knit Serum: potion → `medical supply` (injected)
|
||||
- "Single use." restored on all 4 (was incorrectly stripped in potion cleanup).
|
||||
**Systematic fixes applied across 110 items:**
|
||||
1. **Potion RAW cleanup (13 potions):** Removed "Action/Bonus Action to drink" and "Single use." Kept non-RAW specifics (timing constraints, administer, multi-dose).
|
||||
2. **Throwable subheads (10 items):** 7 area effects → `throwable (range')`, 3 attack-roll items → `thrown weapon (normal'/far')`. Ignition Phial was wrongly subheaded "potion".
|
||||
3. **Save DCs (13 items):** Added rarity-scaled DCs where saves lacked them. 9 Uncommon DC 14, 1 Common DC 12, 3 Rare DC 16.
|
||||
4. **Bold typography (11 items):** Fixed unbold +N bonuses and split-bold dice.
|
||||
5. **Subhead accuracy (19 items):** Corrected salve/poultice, wondrous item, medical supply, consumable variants, ammunition across all flavors.
|
||||
6. **Spell name italics (5 items):** *Magic Missile*, *Feather Fall*, *See Invisibility*, *Mage Hand*, *Detect Magic*, *Silence*, *Pass Without Trace* — all now italic + Heading Case.
|
||||
7. **Dimension expressions (1 item):** 5x10x5 → **5×10×5-foot** with × (U+00D7).
|
||||
|
||||
3. **Missing Save DCs (31 items):** Added rarity-scaled DCs where saves lacked them:
|
||||
- DC 19 (Very Rare): 26 items across all flavors
|
||||
- DC 16 (Rare): Sentry Circle Chalk, Tempest Lash Cartridge, Widow's Kiss Tincture, Pikebreak Charge, Gale Capsule
|
||||
**Human editorial pass 1 (text-based, all 7 flavors):**
|
||||
- Frost-Away Unguent: **wrong mechanics corrected** (was copy of Cinder-to-Soot: burns/fire → frostbite/cold per raw material)
|
||||
- Smoke Lash Cartridge: clarified as area effect, subhead → `ammunition and throwable (60')`
|
||||
- Magebane Flash: "Spell Save DC -2" and "disadvantage to hit" bolded as phrases
|
||||
- Pulsebreaker Bolt: DC "higher of 14 or half damage dealt" (standard concentration check)
|
||||
- Hunter's Promise Oathband: removed long rest recharge — three charges, period
|
||||
- Silence Coin: single use (was 1 charge/recharge at dawn)
|
||||
- Stone of Sensible Silence: three charges (was 2/day)
|
||||
- Lantern of Polite Daylight: ships with 3 fuel crystals (dropped vague "replaceable")
|
||||
- Rag-and-Rum: added 1d4 fire damage, single range throwable (30')
|
||||
- Catstep Powder: tremor-hearing → *tremorsense* or similar *blindsight*
|
||||
- Whisperhook Grapple: "Two uses." (removed recharging from mechanics and lore)
|
||||
- Phosphor Scattershot: "negates *invisibility*", fixed lore paragraph break inside quote
|
||||
- Plus ~30 additional bold scoping, condition italic, subhead corrections
|
||||
|
||||
4. **Bold typography (23 items):** Fixed split-bold dice (`**4d8**+8` → `**4d8+8**`) on 8 recovery items. Bolded +N bonuses (+2 AC, +5/+10 to Stealth, +2/+4 to spell DC/attack), advantage/disadvantage, resistance. Fixed `**resistance to ranged** **damage**` consolidation.
|
||||
**Human editorial pass 2 (PDF visual):**
|
||||
- Lore space extensions (y-5, h+20) on 6 items: Spellguard Veil, Bottled Quicksand, Magebane Flash, Ironstitch Poultice, Spark-Back Salts, Rope of Cooperative Knots
|
||||
- Spellguard Veil: additional font size reduction (9.33→8.8px, line-height 1.25→1.20) to fit all lore
|
||||
- Manaloom Thread: title overflow → split to two lines
|
||||
- Rope of Cooperative Knots: title overflow → hyphenated "ROPE OF CO-" / "OPERATIVE KNOTS"
|
||||
- Razorwire Bracelet: mechanics rect height 84→239 (wrong template rect caused text clipping)
|
||||
|
||||
5. **Throwable subheads (9 items):** Area-effect throws → `throwable (range')`: Bulwark Beads, Tide-Turn Sand, Gravity Bead, Bleakfrost Ampoule, Cyclone Jar, Shattervine Grenado, Blackout Marble, Spiderline Capsule, Gale Capsule.
|
||||
|
||||
6. **Thrown weapon subheads (3 items):** Attack-roll throws → `thrown weapon (normal'/far')`: Bloodglass Spike, Flashchain Bolas, Stormreaver Net.
|
||||
|
||||
7. **Subhead accuracy (3 items):** Focus Salts → `consumable (inhale)`, Smuggler's Breath → `consumable (inhale)`, Heartstop Ampoule → `consumable (apply)`.
|
||||
|
||||
**Lore audit (30 catalog_back_expanded entries):** All 30 already rewritten in Claude Opus voice by prior agent. No boilerplate signals, no repeated closers, no duplicate lore paragraphs, word counts all 99–106 (target 100–120). No rewrites needed. Source tags still say `catalog_back_expanded` but content is in-voice.
|
||||
|
||||
**Not needed:** Lore rewrites (already done), mechanics merge (already done by prior session), reprints (pre-print tier).
|
||||
|
||||
**ITEMS.md, PACKS.md, BALANCE.md** regenerated from updated SVGs.
|
||||
|
||||
**Flashchain Bolas note:** Pre-existing DC 17 on STR save (not the standard DC 19 for Very Rare). May be intentional from consensus — flag for human review.
|
||||
**SVGs done, ITEMS.md regenerated, PDFs rebuilt, packs assembled, QA passed (0 warnings, all 7 flavors matched).**
|
||||
|
||||
### Previously completed
|
||||
|
||||
- **1 Capable** — Full editorial cycle: 29 lore rewrites, systematic fixes, 2 human editorial passes. Complete.
|
||||
- **3 Master** — Two agent passes: typography, DCs, mechanics, lore closers, potion RAW, duplicate lore. Reprints PDF built.
|
||||
- **4 Grandmaster** — Systematic editorial complete. Awaiting human mechanics review.
|
||||
- **0b Intermediate + 0c Specialist** — Lore restructuring (49 items) by prior agent.
|
||||
- **2 Expert** — Lore rewrites + editorial by parallel agent (in progress).
|
||||
- **4 Grandmaster** — Systematic editorial complete (this session). Awaiting human mechanics review.
|
||||
|
||||
### Tooling created this session
|
||||
|
||||
- `scripts/rewrite-mechanics.py` — edits mechanics text (`-m`) and/or subhead (`-s`) in existing SVGs without regenerating the full card.
|
||||
- **SKILL.md** major additions: Cardinal Rule for lore, spell name italics rule, dimension × rule, bold scoping guidance, "never restate RAW" principle, throwable vs thrown weapon distinction, range notation pitfall.
|
||||
|
||||
## Work queue
|
||||
|
||||
@@ -54,48 +68,61 @@ Applied full systematic fixes checklist to all 140 Grandmaster items. 69 SVGs mo
|
||||
| 0a Novice | N/A | N/A | Mini items |
|
||||
| 0b Intermediate | Done | Pending | Short lore acceptable; may need 100-word rewrites eventually |
|
||||
| 0c Specialist | Done | Lore+mechanics done | DC 13 gap remains (printed tier) |
|
||||
| 1 Capable | Done | **Done** | Complete — 2 editorial passes from PDF |
|
||||
| 2 Expert | In progress | In progress | Parallel agent working |
|
||||
| 3 Master | Done | **Done (2nd look)** | Reprints PDF built; 57 OpenClaw lore still to rewrite (non-blocking) |
|
||||
| 1 Capable | Done | **Done** | Complete — 2 editorial passes |
|
||||
| 2 Expert | Done | **Done** | Complete — 2 editorial passes |
|
||||
| 3 Master | Done | **Done (2nd look)** | Reprints PDF built; 57 OpenClaw lore to rewrite (non-blocking) |
|
||||
| 4 Grandmaster | All 140 claude-voice | **Agent pass done** | Awaiting human mechanics review; then PDF export + pack build |
|
||||
| 5 Exit | 21 OpenClaw to rewrite | Pending | After Grandmaster |
|
||||
|
||||
### Next tasks
|
||||
|
||||
**Grandmaster (4 Grandmaster) — HUMAN REVIEW:**
|
||||
|
||||
1. **Human mechanics review.** Agent systematic fixes are complete. Human should review mechanics against table homebrew and tone, especially:
|
||||
- Lingering Damage immunity items (Phoenix Thread Bandage, Spirit-Stitch Lattice)
|
||||
- Flashchain Bolas DC 17 (non-standard for Very Rare — intentional?)
|
||||
- Tea items (Surge Tea, Memory Dew) — currently have "Single use." per tea-item rules
|
||||
- Any homebrew-specific adjustments
|
||||
|
||||
2. **Export PDFs and build packs.** After human review is complete, from main checkout:
|
||||
- Export DM + Player PDFs for all 140 cards
|
||||
- Run `assemble-packs.py "4 Grandmaster"` for pack assembly + QA
|
||||
- Build `All Grandmaster Player Packs.pdf`
|
||||
1. Human mechanics review. Agent systematic fixes are complete. Human should review against table homebrew.
|
||||
2. Export PDFs and build packs after human review.
|
||||
|
||||
**Exit (5 Exit):** 21 OpenClaw lore entries to rewrite. Same pattern. After Grandmaster.
|
||||
|
||||
### Systematic fixes checklist (apply to every tier)
|
||||
|
||||
These were discovered during the Capable editorial and confirmed still needed during the Master second-look. Apply them to every tier before human editorial passes:
|
||||
Apply before human editorial passes:
|
||||
|
||||
1. **Potion RAW cleanup**: Remove "Action/Bonus Action to drink" and "Single use" from all potions. The subhead "potion" implies both per RAW. This was the most common issue in Master (12 of 12 potions affected).
|
||||
1. **Potion RAW cleanup**: Remove "Action/Bonus Action to drink" and "Single use" from all potions. The subhead "potion" implies both.
|
||||
2. **Throwable subheads**: Area effects → `throwable (range')`, attack rolls → `thrown weapon (range'/range')`
|
||||
3. **Bold typography**: All `+N` bonuses, dice rolls, ranges, advantage/disadvantage, resistance/immunity
|
||||
3. **Bold typography**: All `+N` bonuses, dice rolls, ranges, advantage/disadvantage, resistance/immunity, cover, "cannot be surprised", dimension expressions
|
||||
4. **Split-bold scan**: Fix `**Xd?**+N` → `**Xd?+N**` and `N/**M ft**` → `**N/M ft**`
|
||||
5. **Save DCs**: Every save must have rarity-scaled DC. Scan for "save" without "DC". Standard DCs: Common 12, Uncommon 14, Rare 16, Very Rare 19, Legendary 21–25. This was the second most common issue in Master (8 items missing DCs).
|
||||
6. **Subhead accuracy**: Verify subhead matches what the item actually is (coatings→apply, wraps→medical supply, etc.)
|
||||
7. **Lore space**: Check that lore doesn't clip at bottom of card; extend rect if needed
|
||||
8. **Duplicate lore closers**: Scan for repeated final paragraphs (same thought, slightly different wording). This was a systemic lore-generation artifact found in 10 Master items. Likely affects other tiers too.
|
||||
5. **Save DCs**: Every save must have rarity-scaled DC. Common 12, Uncommon 14, Rare 16, Very Rare 19, Legendary 21–25.
|
||||
6. **Subhead accuracy**: Verify subhead matches what the item actually is (coatings→apply, wraps→medical supply, thrown→throwable, etc.)
|
||||
7. **Spell names**: Always *italic* and Heading Case: *Magic Missile*, *Feather Fall*, etc.
|
||||
8. **Dimension expressions**: Use × (U+00D7), not x. Bold the full expression: **5×10×5-foot**.
|
||||
9. **Conditions in italic**: *frightened*, *charmed*, *poisoned*, *prone*, *restrained*, *invisible* (when referring to the condition, NOT when used as a plain adjective).
|
||||
10. **Lore space**: Check that lore doesn't clip at bottom of card; extend rect (y-5, h+20) or reduce font if needed.
|
||||
11. **Duplicate lore closers**: Scan for repeated final paragraphs.
|
||||
12. **Charges not recharges**: Consumable items have finite charges. No "recharges at dawn" unless the item is explicitly not consumable.
|
||||
13. **Normal/far ranges**: Only for attack rolls. Area effects use a single range number.
|
||||
|
||||
### Spell name italics needed in other tiers
|
||||
|
||||
Discovered during Expert catalog-wide scan:
|
||||
|
||||
| Tier | Items |
|
||||
|------|-------|
|
||||
| 1 Capable | *Silence* (Silence Kernel), *Detect Magic* (Witchsight Lens) |
|
||||
| 3 Master | *Detect Magic* (1 item) |
|
||||
| 4 Grandmaster | *Dispel Magic* (1), *Silence* (2), *Counterspell* (lore) |
|
||||
| 5 Exit | *Silence* (Godsbane Silence Bell), *Counterspell* (1) |
|
||||
|
||||
### Dimension × needed in other tiers
|
||||
|
||||
| Tier | Items |
|
||||
|------|-------|
|
||||
| 3 Master | 1 item ("10x10 ft" → **10×10-foot**) |
|
||||
|
||||
### Other outstanding work
|
||||
|
||||
- DC standardization for Specialist (DC 13 → DC 12/14 per rarity) — printed tier, needs reprint decision
|
||||
- 5etools JSON generation for remaining tiers
|
||||
- Bandage-Seal card missing from Specialist Recovery Pack 1 (no SVG exists)
|
||||
- Master tier: 57 OpenClaw lore entries still to rewrite (non-blocking for print; can be done in a future pass)
|
||||
- Master tier: 57 OpenClaw lore entries still to rewrite (non-blocking for print)
|
||||
|
||||
## Lessons learned (cumulative)
|
||||
|
||||
@@ -105,15 +132,22 @@ These were discovered during the Capable editorial and confirmed still needed du
|
||||
4. **Pack assembly needs cross-flavor search.** Use `assemble-packs.py` which searches all flavors and handles aliases.
|
||||
5. **Curly apostrophes in filenames.** SVGs may use `'` (U+2019), PACKS.md uses straight `'`. The pack assembly script normalizes for matching.
|
||||
6. **Always run QA before declaring done.** Check pack page counts, singles vs SVGs, zero warnings.
|
||||
7. **`rebuild-specialist-pdfs.sh` is hardcoded for 0c Specialist.** For other tiers, use an inline bash loop (load prices from ITEMS.md, iterate SVGs, export DM+Player PDFs).
|
||||
8. **Borderline items exist.** If a mechanics-first opening is already funny and specific, it doesn't need an origin hook. Use judgment. Document kept-as-is items in the commit message.
|
||||
9. **PACKS.md names can differ from SVG filenames.** Add aliases to `assemble-packs.py` when new mismatches are found.
|
||||
10. **Clean stale PDFs before QA.** Old exports with outdated prices linger in Singles directories.
|
||||
7. **`rebuild-specialist-pdfs.sh` is hardcoded for 0c Specialist.** For other tiers, use an inline bash loop.
|
||||
8. **Borderline items exist.** Use judgment on lore rewrites. Document kept-as-is items in commit messages.
|
||||
9. **PACKS.md names can differ from SVG filenames.** Add aliases to `assemble-packs.py` when mismatches are found.
|
||||
10. **Clean stale PDFs before QA.** Old exports with outdated prices cause false count mismatches.
|
||||
11. **Lore source tags reflect raw-material provenance, not current authorship.** The text content is what matters.
|
||||
12. **`rewrite-mechanics.py` MUST use argparse flags (-m/-s).** A positional-args version caused catastrophic data loss on 32 cards. See SKILL.md pitfall #22.
|
||||
13. **Two editorial passes are essential.** First pass from ITEMS.md text catches mechanics/logic issues. Second pass from the All Player Packs PDF catches visual issues (bolding, clipping, layout). Different media surface different problems.
|
||||
14. **Lore text field clipping is common.** Extend the shape-inside rect (y-5, h+20) when lore clips at the bottom. See QUICKSTART.md for the technique.
|
||||
15. **Tea items get special treatment.** Brewed teas: "One minute to brew and drink." + "Single use." Potions in bottles: neither (implied by RAW).
|
||||
16. **Duplicate lore closers are a systemic generation artifact.** The lore generation process sometimes produces a final paragraph that restates the penultimate thought with slightly different wording. Found in 10/97 Master items. Scan every tier for this pattern — look for the last two paragraphs sharing the same core image or punchline.
|
||||
17. **Second-look passes catch what first passes miss.** The Master tier had already been through a full agent editorial pass, yet still had 29 items with systemic issues (12 potions, 8 missing DCs, 10 duplicate lore, 1 grammar). A fresh set of eyes applying the same checklist is valuable.
|
||||
18. **Reprints count = pack appearances, not pack + single.** When building replacement PDFs for printed tiers, count each card's occurrences in PACKS.md only. Singles don't need reprinting — the single PDF was already re-exported in place.
|
||||
12. **Never restate RAW on cards.** Potions don't need "Action to drink" or "Single use." Only state what's *new* about the item.
|
||||
13. **Throwable vs thrown weapon distinction.** Area effects get `throwable (range')` with one range number. "On hit" items get `thrown weapon (normal'/far')`.
|
||||
14. **Bold every numeric bonus and penalty.** Also watch for split-bold dice: modifier must be inside the bold.
|
||||
15. **Use `rewrite-mechanics.py` for targeted fixes.** Accepts `-m` (mechanics) and `-s` (subhead) flags. Preserves lore, images, layout.
|
||||
16. **Lore Cardinal Rule: hook opener, mic-drop closer.** First sentence hooks, last sentence is quotable at the table.
|
||||
17. **Two editorial passes are essential.** First from ITEMS.md text, second from All Player Packs PDF. Different media surface different problems.
|
||||
18. **Lore text field clipping is common.** Extend shape-inside rect (y-5, h+20). If still not enough, subtly reduce font size (9.33→8.8px) and line-height (1.25→1.20).
|
||||
19. **Spell names in italic + Heading Case.** *Magic Missile*, *Feather Fall*, *Mage Hand*, etc. Follows RAW presentation. Do a catalog-wide scan when fixing a tier.
|
||||
20. **Dimension expressions use × (U+00D7).** Not lowercase x. Bold the full expression.
|
||||
21. **Charges, not recharges, on consumables.** "Three charges." not "Three charges; recharges at dawn." unless the item is explicitly durable.
|
||||
22. **`rewrite-mechanics.py` MUST use argparse flags (-m/-s).** See SKILL.md pitfall #22.
|
||||
23. **Reprints count = pack appearances, not pack + single.** When building replacement PDFs, count PACKS.md occurrences only.
|
||||
24. **Concentration save DCs should be "the higher of [rarity DC] or half damage."** This prevents the item from nerfing high-damage scenarios where RAW concentration DC would be higher.
|
||||
25. **Wrong-mechanics items exist.** Frost-Away Unguent had identical mechanics to Cinder-to-Soot Ointment (copy-paste from generation). Always verify mechanics against the raw material and item name.
|
||||
|
||||
Reference in New Issue
Block a user