docs: define Korean experience prose contract
This commit is contained in:
DongHyeonka
@@ -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.
|
||||
Reference in New Issue
Block a user