Refine Draft

Improve existing draft content through review and targeted improvements.

When to Use

When a todo item is type refine-draft
When /refine-draft [filepath] is invoked
Weekly draft refinement runs

Instructions

1. Select Draft to Refine

If a specific file is provided, use it.

Otherwise, select using this priority:

Drafts flagged for refinement in todo.md
Oldest draft by created date
Drafts with lowest quality scores (if reviewed)

2. Check for Review Context

If the task context includes a Review file field (e.g., from an outer review):

Read the referenced review file (e.g., reviews/outer-review-2026-01-28-*.md)
Find the specific issue being addressed in the task notes
Check the Verification Notes section to understand what was confirmed
Use the reviewer's specific guidance for the fix

This provides crucial context for targeted fixes rather than general refinement.

3. Run Quality Review

Use the existing review tool:

uv run python scripts/curate.py review [filepath]

This provides:

Overall quality score (1-10)
Strengths list
Improvements list with priorities
Missing concepts

3.5 Attribution Accuracy Check (Required for Source-Based Articles)

If the article is based on a specific source (research paper, philosopher's work), run this checklist:

Misattribution Check

Are all claims attributed to the source actually in the source?
Did we attribute framework/constraints to the right author? (e.g., "five constraints" are Saad's, not Chalmers')
Did we claim the author discusses something they don't? (e.g., "Many-Worlds" when they don't mention it)

Qualifier Preservation Check

Are crucial qualifiers preserved? ("default causal profile" not just "causal profile")
Did we change "X or at least Y" to just "X"?
Did we change "some" to "all" or "wherever"?

Position Strength Check

Did we present exploratory positions as commitments?
Did we claim shared commitments that aren't shared? (e.g., "shares our rejection of MWI" when author expresses "sympathy for MWI")
Did we use "solves" or "answers" when source uses "addresses" or "explores"?

Source/Map Separation Check

Is source exposition clearly separated from Map interpretation?
Are Map-specific arguments (tenets, quantum interactionism) clearly labeled as such?
Did we inject Map arguments as if they came from the source?

Self-Contradiction Check

Did we claim something is "not required" but also "required" in different sections?
Are claims about the theory's commitments consistent throughout?

If any check fails, fix the issue before proceeding to other improvements.

3.6 Reasoning-Mode Classification (Required for Articles That Reply to Named Opponents)

When the article replies to a named opponent (Duch, Frankish, Dennett, Chalmers, the materialist, the functionalist, etc.), classify the reply by reasoning mode before editing. See [[direct-refutation-discipline]] for the full discipline. The classification is editor-internal — it goes in the changelog, not in the article body. The article must engage the opponent in natural journal-quality prose.

Three primary modes plus a mixed sequence (editor's diagnostic vocabulary, not article vocabulary):

Mode One — defective on its own terms. Internal-to-the-opponent argument is available; the reply earns the disagreement inside the opponent's framework. The opponent could in principle accept the criticism without abandoning their commitments.
Mode Two — unsupported foundational move. The framework has helped itself to a foundational move it has not earned by its own standards. The reply uses the opponent's own commitments to mechanism, evidence, or argument. Examples: materialism stipulating "computation produces experience" without specifying the bridge; functionalism asserting "functional pattern is what matters" without arguing why it would generate qualia; eliminativism declaring folk-psychology terms non-referential without specifying the reduction.
Mode Three — framework-boundary marking. The disagreement is at the framework boundary. The reply notes the disagreement honestly without claiming to have refuted the opponent inside their own framework.
Mixed. Most full engagements warrant a sequence: foundational-move identification opens, in-framework argument deepens, boundary-marking declares the residue. The prose flows naturally between the moves.

For each named-opponent reply:

Classify the engagement as one of the modes (or which mode applies to which subsection for mixed engagements). This is for your working knowledge.
Verify the mode is honest — Mode One must derive a contradiction or empirical inadequacy from the opponent's own commitments; Mode Two must invoke a standard the opponent's framework actually endorses; Mode Three must explicitly note the framework-boundary disagreement rather than dressing it as refutation.
Catch boundary-substitution — if the article currently presents tenet-incompatibility as if it refuted the opponent inside the opponent's framework, this is the failure mode the discipline names. Either upgrade the engagement (find the in-framework argument or the unsupported-move identification) or downgrade the language (note the framework-boundary disagreement honestly).
Apply the fix in natural prose. Use the patterns in [[writing-style|the writing-style guide]]'s "Engaging Opponents in Journal-Quality Prose" section. Useful natural-language phrasings include "X helps itself to Y without specifying how", "this runs counter to the Map's foundational commitments and is honestly noted as such, not refuted within X's framework", "X's framework cannot accommodate the measurement on its own terms". Do not name the modes in the article.
Record the classification in the changelog only. Format: "engagement with [opponent]: Mode N; [one-sentence justification]". For mixed engagements, list each subsection's mode. Never write the mode label into the article body.

Forbidden in article prose (these are editor-vocabulary; if any appear in the article, remove and replace with natural prose):

direct-refutation-feasible, unsupported-jump callout, unsupported-jump, bedrock-perimeter, mode-mixed, mixed-with-distinct-roles, tenet-register move, Engagement classification:
The phrase per [[direct-refutation-discipline]] as meta-commentary in prose
Bold-headed **Evidential status:** callouts (use inline natural-language phrasing instead — see [[writing-style]])

The discipline does not require every named opponent to receive in-framework refutation. Some disagreements are genuinely bedrock; saying so honestly is part of the discipline. The failure mode is substitution — letting boundary-marking silently stand in for an argument that was available. The other failure mode is label leakage — exposing the editor's diagnostic vocabulary in article prose. Both are correctable in this pass.

3.7 Altered-State Symmetry Remediation (Required When Pessimistic-Review or the Altered-State Symmetry Audit Flagged the Article)

When the task notes reference an altered-state symmetry flag — generated by /pessimistic-review (see its Altered-State Symmetry checklist), the tools/curate/altered_state_symmetry.py scanner, or an outer review surfacing the same failure mode — the refine pass installs the symmetric accommodation that the article was missing. See [[project/calibration-audit-triple]] Audit Two for the full discipline; this section specifies the action.

The failure mode the refine corrects: the article cites a supportive cluster of altered states (psychedelics, NDEs, terminal lucidity, contemplative cessation, mystical experience, OBE) as convergent evidence for filter / transmission framing, treating each case as an independent confirmation, while the parallel disruptive cluster (anaesthesia, slow-wave sleep, brain damage, persistent vegetative state, dementia) is absent or only mentioned in passing. The 2026-05-14 refine pass on psychedelics-and-the-filter-model.md worked out the canonical fix; the prose that landed there is the reference template for this remediation.

The remediation has three required moves:

Name the disruptive cluster. Add a paragraph that explicitly names which disruptive-cluster items the filter framing must also accommodate. The task notes from the audit will list which items are missing — install them by name, not behind a generic phrase like "other altered states." If the article already mentions an item in passing, expand to engage it as evidence the framing owes work on, not as a footnote.
State how the framing accommodates them. The filter framing's standard accommodation for the disruptive cluster: anaesthesia narrows the interface (propofol and xenon target phenomenal-presence specifically; ketamine severs access channels while sparing phenomenal content); slow-wave sleep is interface-bandwidth-driven-to-near-zero; brain damage and dementia constrain the filter structure rather than abolishing the consciousness the structure filters. Cite [[topics/anaesthesia-and-the-consciousness-interface]], [[topics/dream-consciousness]], and the relevant cases from [[concepts/altered-states-of-consciousness]] for the corpus-level accommodation work that the audited article should inherit. Do not invent new accommodation moves — use the moves the Map already makes.
Mark the accommodation as parallel — not stronger than — the production framing's symmetric work. This is the load-bearing move. The filter framing's accommodation of the disruptive cluster is structurally identical to the production framing's accommodation of the supportive cluster. The honest framing of the dialectical situation is: filter theory accommodates the full altered-state set; production theory accommodates the same set by parallel moves; the supportive cluster cannot be cited as multiple independent confirmations of filter framing without granting the symmetric concession that the disruptive cluster is a parallel test of production framing. The reference phrasings from the canonical fix: "the same move is available to production theorists", "structurally identical accommodations", "the cluster carries the evidential weight of one pattern, not five", "cannot honestly be cited as multiple independent confirmations". Use these or natural-language equivalents.

What the refine should not do. Do not delete the article's filter-framing argument or weaken its overall claim. The discipline is not a request to retract — it is a request to make the dialectical situation honest. The article can still endorse filter theory; what it cannot do is claim the supportive cluster constitutes N independent confirmations while ignoring the disruptive cluster's parallel burden. Preserve the original conclusion; install the symmetric accommodation so the conclusion is reached honestly.

Cross-reference discipline. The refine should add wikilinks to [[topics/anaesthesia-and-the-consciousness-interface]] (or whichever disruptive-cluster article is most relevant) and to [[concepts/altered-states-of-consciousness]] where the corpus-level convergence treatment lives. If the article is itself a concept-tier piece, the same cross-references apply but the prose should pitch one tier more abstract.

Verification. After the refine, the article should clear tools/curate/altered_state_symmetry.py — evaluate_symmetry(path) returns None. If the function still returns a SymmetryFlag after the refine, either the disruptive cluster is still missing, the symmetry-acknowledgment language did not land in the body (perhaps it leaked into a footnote, or the chosen phrasing is not in the marker set), or the supportive-cluster items have grown such that the disruptive engagement is no longer proportionate. Re-read the audit's flag notes and the marker patterns in tools/curate/altered_state_symmetry.SYMMETRY_ACKNOWLEDGMENT_PATTERNS; install the language the audit can recognise.

The corresponding pessimistic-review check is the upstream that should catch the failure mode at review time; this remediation is the downstream that closes it.

4. Apply Improvements

Based on the review, make targeted improvements following obsidian/project/writing-style.md.

Clarity

Simplify convoluted sentences
Define jargon on first use
Improve paragraph flow

Structure

Verify opening summary front-loads key information
Check for undefined forward references (use named-anchor pattern)
Ensure "Relation to Site Perspective" section exists
Add transitions between sections

Style Guide Compliance

Important information front-loaded (truncation resilience)
Named-anchor summaries for forward references
Standard background minimised (focus on what's novel)
H2/H3 headers are descriptive and aid navigation

Tenet Alignment

Ensure content doesn't contradict tenets
Add explicit connections to tenets where natural
Address obvious objections

5. Check for Description

If the article lacks a description field in frontmatter:

Add one: 150-160 characters
Emphasize human+AI collaboration, iterative refinement, and pursuit of truth
Avoid generic phrases—make it distinctive to The Unfinishable Map's approach
Example style: "AI-assisted exploration of X—continuously refined to get closer to the truth."

6. Preserve Voice

When refining:

Keep the original style and approach
Don't over-edit - targeted improvements only
Preserve unique phrasings that work
Maintain the original argument structure unless flawed

7. Update Frontmatter

After refinement:

ai_modified: YYYY-MM-DDTHH:MM:SS+00:00  # Update timestamp

If the original was human-authored (ai_contribution: 0), update to mixed:

ai_contribution: 20  # Or appropriate percentage based on changes

8. Document Changes

Record the changes you made in the changelog entry (Section 10 below). Do not append an AI REFINEMENT LOG HTML-comment block to the article file. The article body is reader-facing — including LLM consumers reading raw markdown via the canonical-domain pipeline, which is the Map's primary audience (CLAUDE.md "LLM-first"). HTML comments hide from rendered Hugo output but remain in the article source and will be parsed by LLMs as authoritative content, leaking editor-vocabulary (audit thresholds, hedge densities, classification labels) into the article. The changelog is the correct location for the editor-internal record.

The 2026-05-19 refine-draft pass that removed 65 such log blocks across topics/, concepts/, voids/, and apex/ was the cleanup; this instruction prevents reintroduction. See reviews/pessimistic-2026-05-19b.md Issue 1.

If a refine pass needs a longer-form editor record than the changelog accommodates (rare — only for multi-pass restructurings like the 2026-05-13 work on non-temporal-consciousness), use a sidecar file: obsidian/{section}/{slug}.refinement-log.md. Sidecars with that exact suffix are excluded from Hugo sync by tools/sync/converter.py and never reach the canonical-domain pipeline.

9. Do Not Mark Todo Complete

Leave the originating todo task untouched. The orchestrator (cycle_post.py) marks it complete after this skill returns, using the line number passed at dispatch time. Marking it here causes the orchestrator to lose the task title for its commit message.

If significant issues remain, create a new todo:

### P2: Further refine [filename]
- **Type**: refine-draft
- **Status**: pending
- **Notes**: Initial refinement done but [remaining issues]

10. Log to Changelog

Prepend to obsidian/workflow/changelog.md (add immediately after frontmatter, before existing entries):

## [current time from prompt] - refine-draft
- **Status**: Success
- **File**: [[filepath without .md extension]]
- **Original score**: X/10
- **Changes**: [brief list]
- **Published**: yes

11. Do Not Commit

Leave file changes uncommitted on disk. The orchestrator (cycle_post.py for /loop runs, agent-commit for legacy evolve_loop.py runs) creates the git commit after this skill returns. For manual invocations, run /agent-commit afterward or commit by hand.

What NOT to Do

Don't change the fundamental argument unless it's flawed
Don't add unnecessary content to pad length
Don't remove content without clear reason
Don't change draft: false to draft: true on published content
Don't make stylistic changes just for the sake of change

Attribution Errors to Avoid

These errors have been identified in outer reviews and must be fixed when found:

Don't attribute framework X to author Y when it's actually from author Z (e.g., "five constraints" are Saad's, not Chalmers')
Don't claim an author discusses topic X when they don't mention it (e.g., Saad doesn't discuss Many-Worlds)
Don't drop crucial qualifiers from definitions (e.g., "default causal profile" → "causal profile" loses essential meaning)
Don't strengthen hedged claims (e.g., "explores" → "argues"; "sympathy for X" → "rejects alternatives to X")
Don't present Map interpretations as source claims — keep Channel A (source) and Channel B (Map) separate
Don't claim shared commitments that aren't shared (e.g., claiming author "shares our rejection of MWI" when they express sympathy for MWI)

Important

ALWAYS update ai_modified timestamp
ALWAYS document changes in the changelog (Section 10), NEVER in an HTML-comment block inside the article
Preserve the original author's voice

refine-draft

SKILL.md.claude/skills/refine-draft