document-haness/docs/superpowers/specs/2026-07-29-korean-experience-prose-contract-design.md

Korean Experience-Prose Contract Design

Goal

ClariDoc must apply one enforceable Korean prose contract when it writes or reviews a Korean technical blog or Korean README. The contract must preserve facts and document structure while making the reader follow the author's experience in consistent 합니다/했습니다 prose.

The change closes the gap between a skill file that describes the desired style and a harness that currently neither passes that style to providers nor checks it before returning PASS.

Scope

The contract applies automatically to:

• a Korean technical_blog using auto, woowahan_tech_blog_ko, or korean_problem_solving_blog;
• every Korean readme.

It does not force first-person retrospective prose onto tutorials, how-to guides, references, troubleshooting guides, explanations, or design documents. Those document types keep their existing style behavior.

The current repository README.md is part of the migration. Its factual content, commands, links, tables, and overall information order remain intact, but its reader-facing Korean prose is revised to the same experience-oriented 합니다/했습니다 style.

Considered Approaches

Prompt-only guidance

Copy the skill text into the drafting prompt. This has the smallest code change, but it leaves no objective proof that the writer or reviser kept the rules. It would preserve the current failure mode in which one correction causes another part of the document to regress.

Opt-in style profile only

Require README authors to select a special style_profile. This avoids adding a document type, but a missing configuration value silently disables the contract. It also makes README structure masquerade as another document type.

Shared contract with a first-class README type

Add readme to the document model and define one shared prose contract used by prompts, lint, reviews, revisions, reports, and tests. This is the selected approach because it makes activation explicit and lets deterministic and model judgment checks cover different parts of the same contract.

Architecture

First-class README document type

DocumentType.README is added to the model and JSON schemas. Its deterministic outline contains these intents in order:

1. problem_value: the concrete problem and why the project exists;
2. principles: the project behavior and boundaries readers must understand;
3. workflow: the end-to-end operating flow;
4. installation: prerequisites and installation;
5. quickstart: the smallest useful execution path and expected result;
6. configuration: the main configuration choices and their effects;
7. verification: how to verify success and diagnose common failure;
8. limits_next: evidence limits, unsupported claims, and the next relevant action.

The planner may refine titles and evidence allocation, but it must preserve these intents and their order just as it does for existing document types.

Shared prose contract

A focused claridoc.style_contracts module owns activation and provider-facing guidance. It exposes:

def korean_experience_contract_applies(brief: Brief) -> bool: ...

def style_guidance(brief: Brief) -> str: ...

The returned guidance includes the same rules in every provider stage:

• open the document and major transitions from a concrete code, screen, request, or problem the author encountered;
• show the initial expectation, then the observed difference;
• explain an unfamiliar term where it first becomes necessary;
• show what the author checked, selected, or changed;
• close the thread with the result, accepted cost, or remaining problem;
• use 저는 or 제가 where it establishes the experience, without repeating it mechanically in every sentence;
• use 했습니다 for observed or performed work and 합니다 for current behavior and technical explanation;
• never invent an emotion, conversation, failure, duration, result, or technical rationale that the evidence does not support;
• preserve code, commands, identifiers, numbers, links, tables, diagrams, claims, evidence status, and outline order.

The guidance describes the canonical paragraph pattern as form, not as facts to copy:

concrete starting point
→ initial expectation
→ observed difference
→ immediate term explanation
→ author action or decision
→ result, cost, or remaining limit

drafting_prompt, review_prompt, and revision_prompt all call this shared module. No stage keeps a separate abbreviated version.

Deterministic checks

Deterministic lint checks only properties that can be recognized without guessing the author's intent.

STYLE002 reports a blocker when reader-facing prose mixes plain declarative endings such as 한다., 있다., 아니다., or ~했다. into a document whose contract requires 합니다/했습니다. Fenced code, headings, Markdown tables, block quotations, image alt text, command output, and quoted spans are excluded. The report consolidates matches and records their count and first locations.

STYLE003 reports a blocker when the opening has no explicit 저는 or 제가 marker, or when fewer than half of substantive H2 sections contain an explicit first-person experience marker. A substantive section is an H2 section with at least one reader-facing prose paragraph; code-only and table-only sections do not count.

The lint report adds:

• style_contract: korean_first_person_experience_v1 or none;
• plain_form_ending_count;
• first_person_marker_count;
• experience_section_count;
• experience_section_coverage.

Because both style issues are blockers, configured error tolerances cannot turn them into a passing result.

Deterministic lint does not try to decide whether a paragraph contains a genuine discovery, whether a term is unfamiliar, or whether the prose sounds natural. Those require model judgment.

Independent review and revision

Every reviewer role receives mandatory prose checks when the contract applies:

• the opening and major transitions follow an experience rather than listing settled facts;
• the paragraph presents an actual expectation or observation rather than inserting 저는 as decoration;
• unfamiliar terms are explained at first need;
• contrasts name the actual component and behavior that differ;
• the document does not manufacture personal history or project rationale;
• 합니다/했습니다 remains consistent outside exempt Markdown regions.

The revision prompt requires a whole-document contract audit after resolving individual findings. This prevents a local rewrite from regressing another section. Each revision round already runs lint and independent reviews again, so the shared contract is re-evaluated before the quality gate can pass.

Skill entry point

The dangling .agents/skills/technical-document-author/SKILL.md reference is replaced with a real authoring skill. It preserves the repository sequence:

Brief
→ SourcePack
→ deterministic outline
→ draft
→ lint and independent reviews
→ revision
→ quality gate
→ reader document and provenance artifacts

For Korean technical blogs and Korean READMEs, the authoring skill requires the Korean prose contract and its sentence-pattern reference. It may not claim completion without lint, review, and quality-gate artifacts. The existing revising-korean-technical-prose skill remains the focused in-place revision skill.

Data Flow

Brief(document_type, language, style_profile)
  → style-contract activation
  → planner keeps deterministic document structure
  → writer receives shared prose guidance
  → deterministic lint checks endings and first-person coverage
  → every reviewer checks experience quality and factual boundaries
  → reviser receives the same guidance plus all findings
  → lint and reviews run again
  → blockers prevent PASS
  → report records style metrics and findings

README Migration

The repository README.md is revised in place with the revising-korean-technical-prose skill:

• existing facts, code blocks, commands, paths, links, tables, and diagrams are preserved;
• Korean reader-facing prose uses 합니다/했습니다;
• the opening and major transitions explain how the harness's failure modes were encountered and how the implemented workflow addresses them;
• no unverified personal event, advice, measurement, or project rationale is added;
• a section documents the activation scope, lint codes, review behavior, and readme brief usage.

The migration is checked separately from generated documents because the repository README is not itself a pipeline output artifact.

Error Handling

• Invalid document_type: readme handling disappears once the enum and schemas are updated; other unknown types remain validation errors.
• Style lint returns actionable locations and correction guidance rather than rewriting content.
• Empty or structure-only documents still fail existing structure and length checks; style metrics do not mask those failures.
• Quoted evidence and code are excluded from deterministic ending checks so original material is not altered to satisfy prose style.
• A model review cannot override a deterministic style blocker.

Testing

Tests are added before production changes.

Model and structure tests

• readme is accepted by Brief and outline schemas;
• readme receives eight unique required intents in the specified order;
• all existing document types retain their current outlines.

Prompt tests

• Korean technical-blog and README draft, review, and revision prompts contain the same contract identifier and required rules;
• English and unrelated Korean document types do not receive the contract;
• the revision prompt requires a whole-document recheck.

Lint tests

• mixed 한다/합니다 prose is a blocker;
• fenced code, headings, tables, block quotations, image alt text, and quoted examples do not cause false positives;
• missing opening first person is a blocker;
• insufficient substantive-section coverage is a blocker;
• a representative experience-oriented technical blog passes;
• a representative Korean README passes;
• unrelated document types retain existing lint behavior.

Pipeline tests

• a style blocker prevents the quality gate from passing even when configured error tolerance is nonzero;
• revision rounds receive the blocker and rerun the contract checks;
• final artifacts record the style contract and findings.

Repository validation

• targeted unit tests are run after each TDD cycle;
• PYTHONPATH=src python3 -m unittest discover -s tests -v is run;
• bash scripts/verify.sh is run if it can preserve the user's unrelated working-tree changes; otherwise its destructive build steps are inspected and an equivalent non-destructive validation set is reported explicitly;
• the revised README.md is scanned outside code and quoted regions for plain declarative endings and reviewed against the experience-flow checklist.

Success Criteria

The implementation is complete only when:

• Korean technical blogs and Korean READMEs receive the contract in every model stage;
• omitting 합니다/했습니다 consistency or first-person experience coverage creates a deterministic blocker;
• qualitative experience flow is a mandatory independent-review concern;
• a revision cannot pass without rerunning the checks;
• readme is a supported contract-first document type;
• the missing technical-author skill entry point exists and requires validation artifacts;
• the repository README follows and documents the same contract;
• all targeted and full regression tests pass.