docs: define Korean experience prose contract

2026-07-29 18:13:40 +09:00
parent 41501b5d06
commit c014b48433
1 changed files with 292 additions and 0 deletions
@@ -0,0 +1,292 @@
 # 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:
 ```python
 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:
 ```text
 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:
 ```text
 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
 ```text
 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.