Skip to content

feat(spec): add report-first capability grill workflow#182

Merged
sungjunlee merged 1 commit into
mainfrom
codex/spec-natural-language-routing
Jun 2, 2026
Merged

feat(spec): add report-first capability grill workflow#182
sungjunlee merged 1 commit into
mainfrom
codex/spec-natural-language-routing

Conversation

@sungjunlee
Copy link
Copy Markdown
Owner

@sungjunlee sungjunlee commented Jun 2, 2026

Summary

  • Make spec-grill report-first with natural-language intent routing instead of argument memorization.
  • Strengthen spec-system-map as the handoff between charter direction and capability grilling.
  • Expand extract-signals.js to group evidence from README, system map, skills, scripts, docs, tests, source surfaces, and commit scopes.
  • Update dogfood spec/system-map.md and spec/capabilities.md to reflect the new workflow boundaries.

Validation

  • node --test skills/spec-grill/scripts/extract-signals.test.js
  • find skills -name '*.test.js' ! -name '*.integration.test.js' -print0 | xargs -0 node --test
  • node skills/dev-backlog/scripts/capabilities-doctor.js --capabilities spec/capabilities.md --strict
  • node skills/dev-backlog/scripts/component-lint.js --sprints-dir backlog/sprints --capabilities spec/capabilities.md
  • node skills/dev-backlog/scripts/objectives-check.js --sprints-dir backlog/sprints --charter spec/charter.md
  • bash skills/dev-backlog/scripts/smoke-test.sh
  • git diff --check

Refs #176
Closes #177
Closes #178
Closes #179
Closes #180
Closes #181

Summary by CodeRabbit

릴리스 노트

  • Documentation

    • 사양 작성 프로세스의 완료 계약(Completion Contract) 요구사항 명확화
    • 모드별(생성/수정/재평가) 후속 산출물 구성 항목 상세화
    • 시스템 맵 및 기능 경계 추천 로직 정렬 및 강화
    • 증거 기반 후보 경계 문서화 추가
  • Tests

    • 증거 수집기 유틸 함수 검증 테스트 추가
    • 신호 추출 통합 테스트 확대

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Jun 2, 2026

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a3be0518-45f1-4deb-8b14-9cd4ecd0e944

📥 Commits

Reviewing files that changed from the base of the PR and between 8a95de4 and cd2c659.

📒 Files selected for processing (8)
  • skills/spec-charter/SKILL.md
  • skills/spec-grill/SKILL.md
  • skills/spec-grill/scripts/extract-signals.js
  • skills/spec-grill/scripts/extract-signals.test.js
  • skills/spec-system-map/SKILL.md
  • skills/spec-system-map/templates/system-map.md
  • spec/capabilities.md
  • spec/system-map.md

Walkthrough

이 PR은 spec-grill의 인자 기반 모드에서 자연어 의도 라우팅으로 전환하고, extract-signals를 증거 그룹화 기반 수집기로 확장하여, spec-system-map을 capability 경계 후보 핸드오프 브릿지로 확립합니다.

Changes

Specification Skill & Contract Updates

Layer / File(s) Summary
Intent Router & Natural-Language Argument Contract
skills/spec-grill/SKILL.md, skills/spec-charter/SKILL.md
spec-grill의 argument-hint가 capability 슬러그에서 자연어 요청으로 변경되고, Intent Router 표가 무인자/모호/후보탐색/특정 슬러그/감사 언급에 따른 라우팅과 쓰기 정책을 문서화합니다. spec-charter는 brownfield 레포에서 spec/system-map.md 존재 여부에 따른 다음 단계 추천 로직을 명확히 합니다.
Grill Report Diagnostic Output Contract
skills/spec-grill/SKILL.md
Grill Report 템플릿이 구체적 Markdown 섹션(증거/누락증거/원시후보/수용·거부·병합·분할/Sharp Questions/3축 발견/다음 제안/권장 편집)을 명시하고, 진단과 뮤테이션을 분리하며, 명시적 요청 없이는 편집하지 않는 규칙을 추가합니다.
Charter Completion Guidance & Next-Step Recommendations
skills/spec-charter/SKILL.md
Create/amend/reassess 모드 완료 계약이 구체적 산출물(생성된 파일, 미해결 가정, 다음 자연어 액션)을 명시하고, 증거 기반 2~5개 경계 후보 이름만 제한적으로 추천하며 하위 인자 암기 요구를 금합니다.
System-Map Candidate Boundaries Handoff Section
skills/spec-system-map/SKILL.md, skills/spec-system-map/templates/system-map.md
Candidate Capability Boundaries 섹션(슬러그, 증거, 소유 계약 표면, 불확실성)이 추가되고, 핸드오프용 짧은 후보라는 제약과 spec-grill 리뷰 요청 가이드가 명시됩니다.
Central Capability Contracts: spec-system-map & spec-grill
spec/capabilities.md
spec-system-map에 후보 경계 handoff 책임이 추가되고, 후보 경계가 수용 capability로 인정되지 않는 Hard Constraint가 추가됩니다. spec-grill의 Goal/In-scope/Expected Behaviors/Hard Constraints가 증거 그룹화, 결정론적 JSON 출력, 단일 capability 블록 편집, 3축 검증 요구사항을 문서화합니다.

Evidence-Grouped Capability Candidate Collection

Layer / File(s) Summary
JSON Schema & Signal Authority Updates
skills/spec-grill/scripts/extract-signals.js
JSON capabilities 스키마가 evidence/missing_evidence 배열(kind/source/content)과 candidate_goal/candidate_scope 필드를 포함하도록 확장되고, buildSignalAuthority 함수가 systemMapFound 입력과 system-map/skill-script-doc-test 표면을 신호 권위에 추가합니다.
Evidence Collection Utilities & Candidate Collectors
skills/spec-grill/scripts/extract-signals.js
slugifyCandidate, 증거 누적 헬퍼(makeEmptyEvidence, addEvidence, addMissingEvidence), 마크다운 파서(getMarkdownSection), 그리고 system-map/README/스킬/스크립트/CLI/소스/문서/테스트 후보 수집기들이 증거 기반 후보 객체를 생성합니다.
Capability Building & Merging Logic
skills/spec-grill/scripts/extract-signals.js
buildCapability가 evidence/missingEvidence 입력을 받아 candidateGoal과 candidateScope를 우선순위 기반으로 재구성하고, mergeCandidates가 증거 후보를 slug 기반으로 병합하며 candidateSignalScore 정렬을 적용합니다.
Extract-Signals Main Flow & Report Output
skills/spec-grill/scripts/extract-signals.js
extractSignals가 spec/system-map.md를 읽고, 모든 증거 소스를 누적 수집하며, system-map 부재 시 missing-evidence를 채우고, evidence/missingEvidence를 buildCapability로 전달합니다. 리포트 출력에 system-map 발견 여부와 증거 kind 지표가 추가됩니다.
Extract-Signals Test Coverage
skills/spec-grill/scripts/extract-signals.test.js
증거 수집기 단위 테스트 스위트가 slugify, system-map/README/스킬/스크립트/소스/문서/테스트 후보 수집을 검증하고, 통합 테스트가 inventory.systemMapFound, evidence 배열, missing_evidence 필드를 단언합니다.

Artifact Documentation & Dogfooding

Layer / File(s) Summary
System-Map Artifact: Candidate Capability Boundaries
spec/system-map.md
Candidate Capability Boundaries 섹션이 sprint-execution, backlog-sync, triage-grooming, spec-charter, spec-system-map, spec-grill, task-progress-reporting 등 7개 경계 후보를 책임 범위 근거와 불확실성 항목과 함께 문서화합니다.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

Possibly related PRs

  • sungjunlee/dev-backlog#160: 이 PR은 #160의 spec-charter/spec-grill 분리 위에 직접 구축되며, skills 계약 문서와 extract-signals.js의 새로운 evidence 수집 파이프라인을 substantial 코드 레벨에서 추가합니다.
  • sungjunlee/dev-backlog#110: 두 PR 모두 spec/capabilities.md를 직접 수정하여 capability 계약 섹션(behavior/hard-constraint 규칙, spec-system-map/spec-grill handoff)을 정의/조정하므로 계약 레벨에서 겹칩니다.

Poem

🐰 자연어 의도가 흐르고,
증거는 그룹으로 모여,
경계 후보는 손잡고,
편집은 오직 확인 후,
스펙은 이제 더 대화체로! 🎯

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/spec-natural-language-routing

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@sungjunlee sungjunlee merged commit f8e3899 into main Jun 2, 2026
1 of 2 checks passed
@sungjunlee sungjunlee deleted the codex/spec-natural-language-routing branch June 2, 2026 02:27
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cd2c659e83

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +573 to +577
const slug = slugifyCandidate(name);
if (!slug || !signal) continue;
const signals = merged.get(slug) || [];
if (!signals.includes(signal)) signals.push(signal);
merged.set(slug, signals);
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Normalize candidate keys before merging evidence

When a commit scope or directory name contains characters that slugifyCandidate rewrites (for example conventional scopes like api/auth, which the parser explicitly accepts), this evidence path creates a second slugged candidate instead of merging with the raw candidate already added from scopeCounts. In a repo with two api/auth commits, extractSignals() now returns both api/auth and api-auth, splitting the same evidence across duplicate raw candidates; normalize the keys used for dirNames/scopeCounts and evidenceCandidates consistently before lookup/set.

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment