Skip to content

docs: CONTRIBUTING + ideation-lead wording cleanup (#95 / #82 #89 follow-up) #101

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sgwannabe merged 2 commits into from
Apr 25, 2026
Merged

docs: CONTRIBUTING + ideation-lead wording cleanup (#95 / #82 #89 follow-up) #101

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
834e6f0
docs(contributing): clarify regression-test path + LESSONS.md locatio…
sgwannabe Apr 25, 2026
71c8b9e
docs(agents): ideation-lead A-4 cascade + sub-agent template alignmen…
sgwannabe Apr 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,9 +106,11 @@ To add a new role, justify why an existing member is insufficient.
### 4. 🐛 Bug fix

Use the bug report issue template. All bug fix PRs must:
- Include a regression test (in `.github/workflows/ci.yml` if hook-related)
- Include a regression test (under `tests/` — fixture, e2e, or boilerplate
lint as appropriate; CI wiring lives in `.github/workflows/ci.yml`)
- Pass `bash scripts/verify-plugin.sh`
- Include a LESSON entry in `LESSONS.md` (root cause + prevention)
- Include a LESSON entry in `plugins/preview-forge/memory/LESSONS.md`
(root cause + prevention)

### 5. 📝 Documentation / spec

Expand Down
31 changes: 20 additions & 11 deletions plugins/preview-forge/agents/ideation/ideation-lead.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,12 @@ model: opus
- I1은 **항상** 3-batch AskUserQuestion을 수행하여 `runs/<id>/idea.spec.json`을 산출 (이미 존재하면 스킵)
- 산출된 `idea.spec.json._filled_ratio`를 4-tier로 매핑 (v1.7.0+ A-4 — B-1과 동시 ship; threshold 0.4 설정 근거: B-1 fast-path 실제 minimum은 5/9 ≈ 0.56 (idea_summary + target_persona + primary_surface + killer_feature + must_have_constraints; nested object는 binary slot 규칙). 5/9에 edge-case safety margin을 더해 0.5 → 0.4로 내림. PR #51 R2 review에서 원래 "4/9 ≈ 0.44" 근거는 binary slot 규칙을 반영하지 못한 오류로 정정 — `idea-clarifier.md` §"Soft anchor 정책" 참조):

| `_filled_ratio` | tier | dispatch 동작 | advocate 받는 신호 |
| `_filled_ratio` | tier (script `mode=`) | dispatch 동작 | advocate 받는 신호 |
|---|---|---|---|
| `≥ 0.7` | **high** | 정상 dispatch, spec을 ground truth로 사용 | `IDEA_SPEC_CONFIDENCE: high` |
| `0.4 ≤ ratio < 0.7` | **medium** | 정상 dispatch, spec을 hint로 사용 (자유 해석 허용 폭 ↑) | `IDEA_SPEC_CONFIDENCE: medium` |
| `0.2 ≤ ratio < 0.4` | **low** | 정상 dispatch + Blackboard `ideation.spec_confidence_tier=low` (이전 `low_spec_quality`의 후계) | `IDEA_SPEC_CONFIDENCE: low` |
| `< 0.2` | **fallback** | **v1.5.4 path**: advocate dispatch 시 `idea.spec.json`을 **전달하지 않음** (`IDEA_SPEC: <not provided — fallback v1.5.4 path>` — `<...>` 플레이스홀더는 리터럴이 아니라 실제 런타임 substitution 결과; 아래 §2 dispatch template과 동일 형식). Blackboard `ideation.spec_fallback_v1_5_4=true` 기록. B-3 "Skip interview" 선택자가 자동으로 이 경로 진입 (ratio ≈ 0.11) | spec 미전달 |
| `≥ 0.7` | **high** (`ground-truth`) | 정상 dispatch, spec을 ground truth로 사용 | `IDEA_SPEC_CONFIDENCE: high` |
| `0.4 ≤ ratio < 0.7` | **medium** (`hint`) | 정상 dispatch, spec을 hint로 사용 (자유 해석 허용 폭 ↑) | `IDEA_SPEC_CONFIDENCE: medium` |
| `0.2 ≤ ratio < 0.4` | **low** (`low-confidence`) | 정상 dispatch + Blackboard `ideation.spec_confidence_tier=low` (이전 `low_spec_quality`의 후계) | `IDEA_SPEC_CONFIDENCE: low` |
| `< 0.2` | **fallback** (`fallback-omit-spec`) | **v1.5.4 path**: advocate dispatch 시 `idea.spec.json`을 **전달하지 않음** (`IDEA_SPEC: <not provided — fallback v1.5.4 path>` — `<...>` 플레이스홀더는 리터럴이 아니라 실제 런타임 substitution 결과; 아래 §2 dispatch template과 동일 형식). Blackboard `ideation.spec_fallback_v1_5_4=true` 기록. B-3 "Skip interview" 선택자가 자동으로 이 경로 진입 (ratio ≈ 0.11) | spec 미전달 (`IDEA_SPEC_CONFIDENCE` 라인도 누락) |

hard gate 없음 — 해커톤 데모 UX 우선. weak-replay short-circuit이 먼저 걸러졌다면 이 경로에는 도달하지 않는다. I_LEAD는 Bash 도구가 없으므로 stderr 대신 Blackboard로 기록.

Expand Down Expand Up @@ -120,9 +120,17 @@ IDEA_SPEC: <not provided — fallback v1.5.4 path>
```text
ROLE: <advocate name> (P01 ~ P26 중 선택)
IDEA: <from idea.json — raw one-liner for creative reframing>
# IDEA_SPEC + IDEA_SPEC_CONFIDENCE 두 줄의 **구조**(어느 라인을 포함할지,
# 어떤 confidence 라벨을 쓸지, fallback에서 IDEA_SPEC_CONFIDENCE를 누락할지)는
# I_LEAD가 §1 Enforcement 단계에서
# `bash scripts/filled-ratio-gate.sh --prompt-fragment runs/<id>/idea.spec.json`
# 의 stdout으로 결정한다 (byte-stable, 4-tier별로 정해진 scaffold). I_LEAD는 그
# scaffold의 `<splice runs/<id>/idea.spec.json …>` 자리에만 실제 JSON 본문을
# 끼워넣고 그 외 wording·라인 유무는 손대지 않는다 — tier 판단·omit 여부 등은
# advocate 쪽에서 second-guess 하지 않는다. fallback-omit-spec tier에서는
# IDEA_SPEC_CONFIDENCE 라인이 의도적으로 누락되어 들어오므로, advocate는 그
# 부재 자체를 "spec 없음" 신호로 해석하면 된다 (별도의 default 값을 만들어내지 말 것).
Comment on lines +123 to +132

@gemini-code-assist gemini-code-assist Bot Apr 25, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The new explanation block correctly describes the contract with scripts/filled-ratio-gate.sh, but its placement and the template structure immediately following it present a few issues:

  1. Template Inconsistency: The template lines (133 and 141) are inconsistent with the script's canonical output. The script outputs IDEA_SPEC_CONFIDENCE before IDEA_SPEC (see filled-ratio-gate.sh lines 106-112), and uses different placeholder wording (verbatim — ground truth). Since the agent is forbidden from touching the scaffold wording (lines 129-130), this discrepancy may cause confusion.
  2. Prompt Pollution: These instructions are placed inside the text code block intended as the prompt template. This may lead the I_LEAD agent to include these internal instructions in the final prompt sent to the Advocate.
  3. Redundancy: Having individual lines for IDEA_SPEC and IDEA_SPEC_CONFIDENCE in the template is redundant now that the agent is instructed to use the script-generated scaffold.
  4. Placeholder Instructions: Per repository guidelines, when documenting instructions for agents that involve placeholders (e.g., <...> notation), you must explicitly state that these placeholders must be replaced with actual runtime values to prevent them from being interpreted as literal strings.

Consider moving these instructions outside the code block and updating the template (lines 133, 141) to use a single placeholder that matches the script's output order and wording, while ensuring the requirement to replace placeholders with runtime values is explicitly stated.

References
  1. When documenting instructions for agents that involve generating files with placeholders (e.g., <...> notation), explicitly state that these placeholders must be replaced with actual runtime values to prevent them from being interpreted as literal strings.

IDEA_SPEC: <from idea.spec.json — structured ground truth from I1 Socratic interview>
# 단, A-4 fallback tier(< 0.2)인 경우 IDEA_SPEC 라인 자체를 빼고
# `IDEA_SPEC: <not provided — fallback v1.5.4 path>`로 대체한다.
# Advocate는 spec의 채워진 필드를 ground truth로 삼되, null/"unknown" 필드는
# 자유 해석 가능. v1.7.0+ A-6: **모든** spec 해석은 반드시 6-tuple의
# spec_alignment_notes에 기록 (null 필드뿐 아니라 그대로 따른 경우도).
Expand All @@ -131,10 +139,11 @@ IDEA_SPEC: <from idea.spec.json — structured ground truth from I1 Socratic int
# 빈 문자열은 preview-card.schema.json (minLength:1) 위반으로 previews.json
# validation이 실패한다.
IDEA_SPEC_CONFIDENCE: <high | medium | low> # v1.7.0+ A-4 — A-4 §1 표 참조.
# `high`: spec 그대로 anchor. divergence 최소화.
# `medium`: spec을 hint로. null 필드는 자유 해석 OK, 채워진 필드는 anchor.
# `low`: spec은 약한 hint. 큰 divergence 허용 (최소 ratio가 4 required only인 경우).
# `fallback` tier에서는 이 라인도 함께 누락된다 (advocate는 spec 받지 않음).
# `high` (mode=ground-truth) : spec 그대로 anchor. divergence 최소화.
# `medium`(mode=hint) : spec을 hint로. null 필드는 자유 해석 OK, 채워진 필드는 anchor.
# `low` (mode=low-confidence) : spec은 약한 hint. 큰 divergence 허용.
# `fallback-omit-spec` tier에서는 이 라인 자체가 fragment에서 누락된다
# (advocate는 spec을 받지 않으며 v1.5.4 marker 한 줄만 본다).
DOMAIN_HINT: <optional, from scripts/detect-surface.sh>
MOCKUP_GUIDANCE: 페르소나에 맞는 self-contained mockup.html (inline CSS only, max 500 lines)
OUTPUT_FORMAT:
Expand Down
Loading