From c014b4843354ad7fc8a41c79b027e53d7a524583 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 29 Jul 2026 18:13:40 +0900 Subject: [PATCH] docs: define Korean experience prose contract --- ...korean-experience-prose-contract-design.md | 292 ++++++++++++++++++ 1 file changed, 292 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-29-korean-experience-prose-contract-design.md diff --git a/docs/superpowers/specs/2026-07-29-korean-experience-prose-contract-design.md b/docs/superpowers/specs/2026-07-29-korean-experience-prose-contract-design.md new file mode 100644 index 0000000..3ab9747 --- /dev/null +++ b/docs/superpowers/specs/2026-07-29-korean-experience-prose-contract-design.md @@ -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.