Skip to content

Commit f024426

Browse files
dev-wooyeondev-wooyeon
authored
docs(blog): 말하기 에세이와 공개 리뷰 스킬 추가 (#121)
* docs(blog): 말하기 에세이와 공개 리뷰 스킬 추가 * docs(review): PR 피드백과 공개 글 검토 규칙 반영
1 parent b97707d commit f024426

10 files changed

Lines changed: 414 additions & 2 deletions

File tree

‎.agents/skills/ark-public-writing-review/SKILL.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
name: ark-public-writing-review
3+
description: Review Ark essay and retrospective blog posts for public publication readiness. Use when evaluating posts/**/index.mdx, a draft pasted by the user, or a request to decide whether an essay or retrospective can move directly from writing to public release. Classify the genre, review its reader promise and evidence, detect AI-like prose and privacy or disclosure risks, and return a publish, revise, or block verdict without editing files unless explicitly asked.
4+
---
5+
6+
# Ark Public Writing Review
7+
8+
## Scope
9+
10+
Review essays and retrospectives. Do not replace the technical-writing pipeline
11+
for technical documentation, tutorials, or troubleshooting guides. Do not infer
12+
that polished sentences make a post publishable.
13+
14+
When reviewing a repository post, read these files first:
15+
16+
1. `docs/blog-quality-guide.md`
17+
2. the target `posts/**/index.mdx`
18+
3. its sibling `meta.json`
19+
20+
If the user provides prose instead of a path, use the supplied prose and state
21+
which repository checks could not be performed.
22+
23+
## Workflow
24+
25+
### 1. Classify the post
26+
27+
Choose one primary type:
28+
29+
- `essay`: a point of view, interpretation, principle, or explanation.
30+
- `retrospective`: a real event or project with context, decisions, failures,
31+
changed behavior, and next-time rules.
32+
33+
If the post is mainly a review of an external object, route to the existing
34+
blog review workflow instead of forcing it into these two types. If it is a
35+
technical document with reader instructions as its main goal, route to the
36+
`technical-writing-pipeline` skill.
37+
38+
### 2. Run the release review
39+
40+
Review the whole draft before suggesting sentence edits. Check:
41+
42+
- reader promise: `Who`, `What`, `Why`, and `How`
43+
- title and first three paragraphs: promise, tension, and payoff
44+
- structure: each section advances one central thought
45+
- specificity: scenes, constraints, examples, decisions, or evidence
46+
- originality: the author's own observation rather than generic advice
47+
- usefulness: a reusable idea, changed behavior, or decision rule remains
48+
- prose: directness, rhythm, repetition, vague abstraction, and AI patterns
49+
- public safety: secrets, personal data, NDA, workplace identifiers,
50+
unsupported allegations, and claims that need verification
51+
52+
For essays, additionally check that the argument is visible, personal material
53+
supports the argument, and the ending leaves a durable thought rather than a
54+
summary slogan.
55+
56+
For retrospectives, additionally check situation, turning point, decision,
57+
failure or trade-off, result, changed behavior, and next-time rule. Do not
58+
accept "I learned" without what changed afterward.
59+
60+
### 3. Assign the verdict
61+
62+
Use the strictest applicable result:
63+
64+
- `publish`: no blocking or must-fix finding; public risk is acceptable; the
65+
post is coherent and useful now.
66+
- `revise`: the post is safe to publish but has one or more must-fix content,
67+
structure, evidence, or prose issues.
68+
- `block`: disclosure, privacy, factual, attribution, or audience risk must be
69+
resolved before publication; also use this when the reader promise is absent.
70+
71+
Do not use a score average to hide a blocking issue. Mark uncertain factual or
72+
safety claims as `verify`, not as passed.
73+
74+
If the target is an Ark Tech post, inspect the `qualityReview` core fields
75+
(`philosophy`, `design`, `implementation`) even when `qualityReview` is absent.
76+
Report existing scores without inventing them. If a required core score is
77+
missing, mark the result `verify` and do not return `publish`; use `block` for
78+
a public-release decision and `revise` while the post remains private. The
79+
public policy threshold is a repository rule, not a substitute for editorial
80+
judgment.
81+
82+
### 4. Run repository checks when applicable
83+
84+
When reviewing a file in Ark and the user asks for release readiness, run the
85+
smallest relevant checks after the editorial verdict:
86+
87+
- `npm run content:audit`
88+
- `npm run lint` when MDX or source changes affect linted files
89+
- `npm run build` for the final public-release check
90+
91+
Report commands that were not run. Do not change `visibility` automatically.
92+
93+
## Output
94+
95+
Return this compact report:
96+
97+
```markdown
98+
## Verdict
99+
- type: essay | retrospective
100+
- publication: publish | revise | block
101+
- summary: ...
102+
103+
## Must Fix
104+
1. [P0/P1] ...
105+
106+
## Keep
107+
- ...
108+
109+
## Review
110+
| Area | Result | Finding |
111+
| --- | --- | --- |
112+
| reader promise | pass | ... |
113+
| structure | pass | ... |
114+
| specificity | pass | ... |
115+
| originality | pass | ... |
116+
| usefulness | pass | ... |
117+
| prose | pass | ... |
118+
| public safety | pass | ... |
119+
120+
## Checks
121+
- editorial: ...
122+
- repository: ...
123+
```
124+
125+
Use `Must Fix` only for actionable issues. If there are no must-fix items,
126+
write `없음`. Keep the report shorter for a quick review request. Do not emit a
127+
`meta.json` patch unless the user asks to update repository metadata.

‎.agents/skills/ark-public-writing-review/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Ark Public Writing Review"
3+
short_description: "에세이와 회고글의 공개 발행 가능성을 검토합니다"
4+
default_prompt: "Use $ark-public-writing-review to review this essay or retrospective for public publication readiness."

‎docs/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# 문서 인덱스
22

3-
Last updated: 2026-07-22
3+
Last updated: 2026-07-24
44

55
이 인덱스는 현재 코드베이스와 함께 유지해야 하는 문서만 추적한다. 계속
66
업데이트할 문서가 아니라면 삭제하거나, 오래 남겨야 하는 결정만 ADR로 옮긴다.
@@ -49,6 +49,7 @@ Last updated: 2026-07-22
4949
- `docs/adr/0048-centralize-blog-publication-rules.md`
5050
- `docs/adr/0049-share-publication-policy-data-with-audit.md`
5151
- `docs/adr/0050-retire-series-navigation-and-enforce-listed-post-policy.md`
52+
- `docs/adr/0052-use-repo-local-public-writing-review-workflow.md`
5253
- `docs/blog-quality-guide.md`
5354
- `docs/content-publication-candidates.md`
5455
- `docs/database/db-schema.md`

‎docs/adr/0052-use-repo-local-public-writing-review-workflow.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# 0052. 공개 글 검토에 repo-local writing review workflow를 사용한다
2+
3+
Date: 2026-07-24
4+
Status: Accepted
5+
6+
## 배경
7+
8+
에세이와 회고글은 기술 문서와 다른 공개 기준을 가진다. 문장 품질만
9+
확인하면 독자 약속, 개인 경험의 구체성, 공개 위험, 제목과 도입의 적합성을
10+
놓칠 수 있다.
11+
12+
기존 `blog-growth-review`는 점수화와 개선 우선순위를 담당하지만, 공개 가능
13+
여부를 판단하는 전체 편집 흐름과 기술 문서 라우팅을 담당하지 않는다.
14+
15+
## 결정
16+
17+
- `.agents/skills/ark-public-writing-review`를 에세이와 회고글의 공개 전
18+
검토 workflow로 사용한다.
19+
- workflow는 `docs/blog-quality-guide.md`, 대상 글, `meta.json`을 먼저 읽고
20+
독자 약속, 구조, 구체성, 독창성, 유용성, 문장, 공개 안전성을 검토한다.
21+
- 결과는 `publish`, `revise`, `block`으로 구분한다. `visibility`는 자동으로
22+
바꾸지 않는다.
23+
- Tech 글은 `philosophy`, `design`, `implementation` 점수 누락을
24+
`verify`로 처리한다. 공개 결정에서는 `block`, private 상태에서는
25+
`revise`로 판정한다.
26+
- 기술 문서는 `technical-writing-pipeline`으로 라우팅하고, 제목과 성장
27+
점수 검토는 각 repo-local skill의 책임으로 유지한다.
28+
- release readiness 요청에서는 `content:audit`, 필요한 경우 `lint`와
29+
`build`를 실행한다.
30+
31+
## 결과
32+
33+
- 에세이와 회고글도 작성 후 공개까지 같은 검토 기준을 반복 적용할 수 있다.
34+
- 점수화 결과와 편집 판정을 분리해, 점수 평균이 공개 위험을 가리지 않는다.
35+
- private 기본 정책을 유지하면서 공개 전 확인 항목을 명시할 수 있다.
36+
- 기술 문서용 workflow와 개인 글용 workflow가 서로의 범위를 침범하지 않는다.
37+
38+
## 검토한 대안
39+
40+
- 하나의 generic prompt 사용: 빠르지만 저장소 정책과 검토 결과 형식이
41+
고정되지 않는다.
42+
- `blog-growth-review`에 공개 판정까지 추가: 점수화와 편집 안전성의 책임이
43+
섞인다.
44+
- 기술 문서와 에세이를 하나의 workflow로 통합: 독자 약속과 검증 기준이
45+
달라 불필요한 분기와 누락이 생긴다.
46+
47+
## 검증
48+
49+
- 대상 글에 `npm run content:audit`, `npm run lint`, `npm run build`를
50+
실행한다.
51+
- skill 문서의 출력 형식과 Tech 점수 누락 규칙을 리뷰한다.
52+
53+
## Related History
54+
55+
- `7d09712`: 공개 글 리뷰 skill과 말하기 에세이 추가
56+
- [ADR 0022](0022-default-new-posts-to-private.md): 새 글 private 기본값
57+
- [ADR 0023](0023-run-the-release-quality-gate-in-ci.md): release quality gate
58+
- [ADR 0026](0026-use-repo-local-title-review-skill.md): repo-local 제목 리뷰
59+
- [ADR 0016](0016-use-content-type-and-growth-review-scores.md): 글 형식과 성장 점수 분리

‎docs/adr/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Architecture Decision Records
22

3-
Last updated: 2026-07-22
3+
Last updated: 2026-07-24
44

55
이 디렉터리는 커밋 히스토리에서 복원한 아키텍처 의사결정을 기록한다.
66
ADR은 AI 협업 가이드와 별개의 문서다. 사람이 결정했든 AI가 초안을
@@ -69,6 +69,7 @@ ADR은 AI 협업 가이드와 별개의 문서다. 사람이 결정했든 AI가
6969
| [0049](0049-share-publication-policy-data-with-audit.md) | Accepted | 발행 정책 데이터를 content audit과 공유한다 |
7070
| [0050](0050-retire-series-navigation-and-enforce-listed-post-policy.md) | Accepted | 시리즈 탐색을 제거하고 발행 정책을 repository에서 강제한다 |
7171
| [0051](0051-use-viewport-specific-reading-layout-and-type-scale.md) | Accepted | viewport별 읽기 레이아웃과 타이포그래피 스케일을 사용한다 |
72+
| [0052](0052-use-repo-local-public-writing-review-workflow.md) | Accepted | 공개 글 검토에 repo-local writing review workflow를 사용한다 |
7273

7374
## 작성 조건
7475

0 commit comments

Comments
 (0)