jhste-skills 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## Unreleased
+## 0.8.0 - 2026-07-26
+
+### Added
+- Added `jhste-to-spec` to synthesize established decisions and repository evidence into a draft-first engineering specification without inventing unresolved requirements.
+- Added `jhste-diagnosing-bugs` for difficult bugs and performance regressions that need reproduction, falsifiable hypotheses, targeted instrumentation, or measurement before a fix is clear.
+- Added `jhste-handoff` for compact executor-neutral implementation handoffs with optional outcome-based phase documents, parallel ownership, verification evidence, and an exact resume point.
+- Added `jhste-implementation-finalizer` to independently audit and finish existing or partial implementations, synchronize an existing handoff, and complete already-authorized updates to the same pull request.
+- Added static trigger, non-trigger, handoff, and external-write scenario contracts for the eight changed skills, covering 48 cases.
+- Added `THIRD_PARTY_NOTICES.md` and included it in the npm package for upstream attribution and MIT license preservation.
+
+### Changed
+- Refined `jhste-coding` to frame caller contracts, owning modules, test seams, bounded preparatory refactors, difficult-bug diagnosis, and the boundary with independent implementation finalization.
+- Refined `jhste-to-spec` to keep behavioral specifications separate from worker progress, ownership, and resume state.
+- Refined `jhste-to-tickets` to inspect repository seams and validation paths, keep preparatory work bounded, route unresolved behavior before ticketing, follow established label policy, and avoid duplicating local handoff state in issues.
+- Refined `jhste-grill` to resolve every consequential decision branch while continuously updating settled glossary entries and automatically writing qualifying ADRs.
+- Refined `jhste-domain-modeling` to update the repository glossary as terms settle and automatically record accepted decisions that meet the ADR threshold.
+- Expanded package metadata, validation, and both READMEs from six to ten independent skills.
 
 ## 0.7.0 - 2026-07-23
 

package/README.en.md

@@ -6,29 +6,37 @@ A personal engineering skill set maintained around GPT-5.6's outcome-first, lean
 
 ## Skills
 
-- **`jhste-coding`** — implements features, fixes bugs, and refactors code with a small change and relevant validation.
-- **`jhste-grill`** — sharpens a plan or design through one consequential decision question at a time.
+- **`jhste-coding`** — implements sufficiently understood features, bug fixes, and refactors with a small change and relevant validation.
+- **`jhste-diagnosing-bugs`** — diagnoses difficult bugs and performance regressions whose cause or correct fix is uncertain through reproduction, hypotheses, and measurement.
+- **`jhste-grill`** — resolves consequential decision branches one question at a time while continuously maintaining settled domain context and ADRs.
+- **`jhste-domain-modeling`** — clarifies domain terms, boundaries, and relationships, immediately recording settled glossary entries and qualifying ADRs.
+- **`jhste-to-spec`** — synthesizes an already discussed or defined change into a reviewable engineering specification grounded in repository evidence.
+- **`jhste-to-tickets`** — splits defined work into GitHub parent/sub-issues with native dependencies.
+- **`jhste-handoff`** — creates executor-neutral implementation handoffs with ownership, phase progress, verification, blockers, and an exact resume point.
+- **`jhste-implementation-finalizer`** — independently audits and finishes an existing implementation, synchronizes its handoff, and completes already-authorized PR updates.
 - **`jhste-pr-review`** — reviews explicitly requested PRs against the actual diff and posts only high-confidence actionable findings.
 - **`jhste-review-followup`** — validates existing PR feedback and pushes only justified fixes to the existing PR branch.
-- **`jhste-to-tickets`** — splits defined work into GitHub parent/sub-issues with native dependencies.
-- **`jhste-domain-modeling`** — clarifies domain terms, boundaries, and relationships, and records them in a glossary or ADR when requested.
 
-The skills do not require or automatically call one another. A request may use more than one when it contains multiple intents. `jhste-pr-review` handles the initial review; `jhste-review-followup` handles feedback already present on a PR, but neither depends on the other.
+The skills do not require or automatically call one another. A request may use more than one when it contains multiple intents. Consequential choices can be resolved with `jhste-grill` and domain language with `jhste-domain-modeling`; settled behavior can become a `jhste-to-spec` artifact and GitHub work can be split with `jhste-to-tickets`. `jhste-handoff` preserves execution state for any implementation mechanism, while `jhste-implementation-finalizer` independently verifies and completes the resulting implementation. Difficult root-cause work remains with `jhste-diagnosing-bugs`, and a known correction belongs to `jhste-coding`.
 
 ## Behavioral boundaries
 
-- `jhste-coding` applies only when repository code must change.
-- `jhste-grill` applies when the user wants an interview or decision stress test; ordinary ambiguity alone must not start a long interview.
-- `jhste-pr-review` applies only to an explicit PR code-review request. That request authorizes high-confidence inline review comments with the `COMMENT` event; approval or change-request decisions still require the exact explicit action.
-- `jhste-review-followup` applies only when the user explicitly asks to handle existing PR review feedback. It validates each item, fixes justified root causes, validates the result, and updates the existing PR branch. It does not merge, reply, resolve threads, change issues, or clean up work artifacts.
-- `jhste-to-tickets` drafts by default. It writes to GitHub only when the user explicitly asks to create, post, or publish the issues.
-- `jhste-domain-modeling` analyzes and proposes by default. It edits repository documentation only when the user asks to record or apply the decisions.
+- `jhste-coding` applies to implementation and fixes whose code-change path is sufficiently understood. Problems centered on uncertain root cause, intermittency, or performance measurement belong to `jhste-diagnosing-bugs`; an existing worker result that needs an independent completion audit belongs to `jhste-implementation-finalizer`.
+- `jhste-diagnosing-bugs` applies when root-cause work needs a reproduction signal, competing hypotheses, instrumentation, or measurement. It avoids imposing the full diagnostic loop on an obvious typo, direct compile or lint error, or already established fix.
+- `jhste-grill` applies when the user wants an interview or decision stress test; ordinary ambiguity alone does not start a long interview. In a writable repository it maintains settled glossary entries and qualifying ADRs unless the request is analysis-only or forbids edits.
+- `jhste-domain-modeling` owns focused domain-language clarification and the corresponding glossary and qualifying ADR updates, not incidental code naming or generic architecture discussion.
+- `jhste-to-spec` defines settled behavior, contracts, validation, and scope. It does not act as a worker-progress tracker or durable resume document.
+- `jhste-to-tickets` drafts or publishes a GitHub issue graph. It does not duplicate local handoff state across issue bodies.
+- `jhste-handoff` runs only for an explicit handoff, resume, or implementation-context request. It follows an existing repository convention or defaults to `docs/handoff/indexes/` plus optional `docs/handoff/phases/`, and it remains independent of the eventual executor.
+- `jhste-implementation-finalizer` starts from an existing or partial implementation and treats completion claims as unverified. It fixes in-scope gaps and may commit, push, or update the named existing PR only when those writes were already authorized; it does not merge by default.
+- `jhste-pr-review` applies only to an explicit review-only request and does not modify the branch.
+- `jhste-review-followup` applies only when existing PR feedback defines the scope. It is not the general completion workflow for a worker result or partially implemented branch.
 
-This package intentionally omits TDD, debugging-process, Wayfinder, and architecture-audit workflows. It favors the model's baseline capabilities and repository CI or guidance, adding another skill only after a repeated real failure justifies it.
+This package does not include a mandatory TDD workflow, Wayfinder, a generic delivery orchestrator, or a separate architecture-audit skill. Existing skills and available implementation mechanisms can be composed without adding a routing layer until repeated real failures justify its context and maintenance cost.
 
 ## Install user-wide from npm
 
-This package has no CLI. It distributes the six skills and their Codex metadata.
+This package has no CLI. It distributes the ten skills and their Codex metadata.
 
 ```sh
 npm install -g jhste-skills
@@ -45,7 +53,7 @@ mkdir -p "$HOME/.agents/skills"
 cp -R skills/. "$HOME/.agents/skills/"
 ```
 
-If another agent expects a different global skills directory, copy the six directories under `skills/` there. This package does not require project-local skill copies.
+If another agent expects a different global skills directory, copy the ten directories under `skills/` there. This package does not require project-local skill copies.
 
 ## Development and validation
 
@@ -54,4 +62,6 @@ npm test
 npm pack --dry-run
 ```
 
-Pushing a `v*.*.*` release tag runs GitHub Actions checks and publishes the package through npm trusted publishing.
+`npm test` checks package, metadata, and documentation consistency plus 48 static routing scenarios for the eight changed skills. The fixture does not invoke a model or measure live automatic-trigger accuracy.
+
+External sources and license attribution are recorded in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Pushing a `v*.*.*` release tag runs GitHub Actions checks and publishes the package through npm trusted publishing.

package/README.md

@@ -2,33 +2,41 @@
 
 한국어 | [ENG](README.en.md)
 
-GPT-5.6의 outcome-first, lean-prompt 지침에 맞춰 관리하는 개인용 엔지니어링 스킬 모음입니다. 각 스킬은 독립적으로 동작하며, 필요한 경우 Codex가 사용자 의도에 맞춰 자동 호출할 수 있습니다.
+GPT-5.6의 outcome-first, lean-prompt 지침에 맞춰 관리하는 개인용 엔지니어링 스킬 모음입니다. 각 스킬은 독립적으로 동작하며, 사용자 의도가 좁은 trigger와 맞으면 자동 선택될 수 있습니다.
 
 ## 스킬
 
-- **`jhste-coding`** — 기능 구현, 버그 수정, 리팩터링을 작은 변경과 관련 검증으로 완료합니다.
-- **`jhste-grill`** — 계획이나 설계를 한 번에 하나의 중요한 결정 질문으로 구체화합니다.
-- **`jhste-pr-review`** — 사용자가 명시적으로 요청한 PR을 실제 diff 기준으로 리뷰하고 확신도 높은 actionable finding만 코멘트합니다.
-- **`jhste-review-followup`** — 기존 PR 피드백을 검증하고 타당한 수정만 기존 PR 브랜치에 반영합니다.
-- **`jhste-to-tickets`** — 명확해진 작업을 GitHub 부모/sub-issues와 native dependency로 분할합니다.
-- **`jhste-domain-modeling`** — 도메인 용어, 개념 경계, 관계를 명확히 하고 요청 시 glossary나 ADR에 반영합니다.
+- **`jhste-coding`** — 충분히 이해된 기능, 버그 수정, 리팩터링을 작은 변경과 관련 검증으로 구현합니다.
+- **`jhste-diagnosing-bugs`** — 원인이나 올바른 수정이 불확실한 어려운 버그와 성능 저하를 재현, 가설, 측정으로 진단합니다.
+- **`jhste-grill`** — 중요한 결정 분기를 한 번에 한 질문씩 해소하면서 확정된 도메인 문맥과 ADR을 계속 갱신합니다.
+- **`jhste-domain-modeling`** — 도메인 용어, 경계, 관계를 명확히 하고 확정된 glossary 항목과 필요한 ADR을 바로 기록합니다.
+- **`jhste-to-spec`** — 이미 논의되거나 정의된 변경을 저장소 근거에 맞춘 검토 가능한 엔지니어링 명세로 정리합니다.
+- **`jhste-to-tickets`** — 정의된 작업을 GitHub parent/sub-issue와 native dependency로 나눕니다.
+- **`jhste-handoff`** — 특정 실행 도구와 무관하게 소유권, 단계 진행, 검증, blocker, 정확한 재개 지점을 보존하는 구현 handoff를 만듭니다.
+- **`jhste-implementation-finalizer`** — 기존 또는 부분 구현을 독립적으로 감사하고 부족한 부분을 직접 고쳐 검증하며, 이미 승인된 동일 PR 업데이트까지 완료합니다.
+- **`jhste-pr-review`** — 명시적으로 요청된 PR을 실제 diff 기준으로 검토하고 신뢰도 높은 실행 가능한 지적만 게시합니다.
+- **`jhste-review-followup`** — 기존 PR 피드백을 검증하고 정당한 수정만 기존 PR 브랜치에 반영합니다.
 
-스킬은 서로를 강제로 호출하지 않습니다. 하나의 요청이 여러 의도를 포함하면 함께 사용할 수 있습니다. `jhste-pr-review`는 최초 리뷰를 담당하고, `jhste-review-followup`은 기존 PR에 이미 달린 피드백을 처리하지만 서로를 필수로 요구하지 않습니다.
+스킬은 서로를 의무적으로 호출하지 않습니다. 한 요청에 여러 의도가 있으면 필요한 스킬을 조합할 수 있습니다. 중요한 선택은 `jhste-grill`, 도메인 언어는 `jhste-domain-modeling`, 확정된 동작 명세는 `jhste-to-spec`, GitHub 작업 분해는 `jhste-to-tickets`가 담당합니다. `jhste-handoff`는 어떤 구현 수단을 사용하더라도 실행 상태를 보존하고, `jhste-implementation-finalizer`는 그 결과를 독립 검증하고 끝까지 완성합니다. 원인 불명의 문제는 `jhste-diagnosing-bugs`, 수정 방향이 이미 명확한 구현은 `jhste-coding`에 속합니다.
 
 ## 동작 경계
 
-- `jhste-coding`은 실제 코드 변경 요청에만 사용합니다.
-- `jhste-grill`은 사용자가 인터뷰나 결정 검증을 원할 때 사용하며, 단순한 모호성만으로 긴 인터뷰를 시작하지 않습니다.
-- `jhste-pr-review`는 사용자가 PR 코드 리뷰를 명시적으로 요청한 경우에만 사용합니다. 해당 요청은 확신도 높은 인라인 코멘트를 `COMMENT` event로 게시하는 것까지 승인하며, approve나 request changes는 해당 동작을 정확히 명시해야 합니다.
-- `jhste-review-followup`은 사용자가 기존 PR 리뷰 피드백 처리를 명시적으로 요청한 경우에만 사용합니다. 각 항목의 타당성을 검증하고, 타당한 root cause만 수정·검증한 뒤 기존 PR 브랜치를 업데이트합니다. 병합, 답글, thread resolve, 이슈 변경, 작업 흔적 정리는 수행하지 않습니다.
-- `jhste-to-tickets`는 기본적으로 초안을 만듭니다. 사용자가 GitHub에 생성·게시하라고 명시한 경우에만 외부 쓰기를 수행합니다.
-- `jhste-domain-modeling`은 기본적으로 분석하고 제안합니다. 사용자가 기록·반영을 요청한 경우에만 저장소 문서를 수정합니다.
+- `jhste-coding`은 구현 경로가 충분히 명확한 코드 변경을 담당합니다. 원인 규명이나 성능 측정이 핵심이면 `jhste-diagnosing-bugs`, 기존 작업 결과를 독립 감사하고 마무리해야 하면 `jhste-implementation-finalizer`를 사용합니다.
+- `jhste-diagnosing-bugs`는 재현 신호, 경쟁 가설, 계측, 측정이 필요한 문제를 담당하며, 명백한 오타나 이미 원인이 확인된 수정에는 과한 진단 절차를 강요하지 않습니다.
+- `jhste-grill`은 사용자가 인터뷰나 의사결정 검증을 원할 때만 동작합니다. 쓰기 가능한 저장소에서는 분석 전용 또는 수정 금지 요청이 아닌 한 확정된 glossary와 ADR을 갱신합니다.
+- `jhste-domain-modeling`은 도메인 언어와 개념 경계를 담당하며, 단순 변수명 변경이나 일반적인 아키텍처 설명을 가로채지 않습니다.
+- `jhste-to-spec`은 확정된 동작, 계약, 검증, 범위를 정의합니다. 작업자 진행 상황이나 영구 재개 문서로 사용하지 않습니다.
+- `jhste-to-tickets`는 GitHub issue graph를 초안 작성하거나 게시합니다. 로컬 handoff 상태를 여러 issue 본문에 중복하지 않습니다.
+- `jhste-handoff`는 명시적인 handoff, 재개, 구현 문맥 요청에서만 동작합니다. 저장소 관례가 없으면 `docs/handoff/indexes/`와 필요할 때만 `docs/handoff/phases/`를 사용하며, 최종 실행 수단과 독립적입니다.
+- `jhste-implementation-finalizer`는 기존 또는 부분 구현에서 시작하고 완료 보고를 증거로 믿지 않습니다. 범위 내 누락을 직접 고치며, commit·push·기존 PR 업데이트는 이미 허가된 경우에만 수행하고 기본적으로 merge하지 않습니다.
+- `jhste-pr-review`는 검토 전용 요청에만 적용되며 브랜치를 수정하지 않습니다.
+- `jhste-review-followup`은 이미 존재하는 PR 피드백이 범위를 정의할 때만 적용됩니다. 일반적인 작업자 결과 마무리 용도가 아닙니다.
 
-TDD, 디버깅 절차, Wayfinder, 아키텍처 감사 workflow는 포함하지 않습니다. 모델의 기본 능력과 저장소 자체의 CI·지침을 우선하고, 반복되는 실제 실패가 확인될 때만 새 스킬을 추가합니다.
+이 패키지는 의무적인 TDD workflow, Wayfinder, 범용 delivery orchestrator, 별도 architecture-audit 스킬을 포함하지 않습니다. 현재 스킬과 사용 가능한 구현 수단만으로 조합할 수 있으며, 반복되는 실제 실패가 확인되기 전에는 라우팅 계층을 추가해 문맥과 유지보수 비용을 늘리지 않습니다.
 
-## npm으로 사용자 전역 설치
+## npm에서 사용자 전역 설치
 
-이 패키지는 CLI를 제공하지 않습니다. npm 패키지는 여섯 스킬과 Codex 메타데이터를 배포하는 번들입니다.
+이 패키지는 CLI를 제공하지 않습니다. 열 개 스킬과 Codex metadata를 배포합니다.
 
 ```sh
 npm install -g jhste-skills
@@ -36,7 +44,7 @@ mkdir -p "$HOME/.agents/skills"
 cp -R "$(npm root -g)/jhste-skills/skills/." "$HOME/.agents/skills/"
 ```
 
-npm 패키지를 업데이트한 뒤에는 복사 명령을 다시 실행해야 설치된 스킬도 갱신됩니다. Codex가 변경된 스킬을 표시하지 않으면 다시 시작하세요.
+npm 패키지를 업데이트한 뒤 copy 명령을 다시 실행하세요. 갱신된 스킬이 보이지 않으면 Codex를 재시작하세요.
 
 ## 저장소에서 사용자 전역 설치
 
@@ -45,7 +53,7 @@ mkdir -p "$HOME/.agents/skills"
 cp -R skills/. "$HOME/.agents/skills/"
 ```
 
-다른 에이전트가 별도 전역 skills 디렉터리를 요구하면 `skills/` 아래의 여섯 디렉터리를 그 위치로 복사하세요. 이 패키지는 프로젝트별 스킬 복사본을 요구하지 않습니다.
+다른 agent가 다른 전역 skills 디렉터리를 사용하면 `skills/` 아래 열 개 디렉터리를 그 위치에 복사하세요. 프로젝트별 복사본은 필수가 아닙니다.
 
 ## 개발 및 검증
 
@@ -54,4 +62,6 @@ npm test
 npm pack --dry-run
 ```
 
-릴리스 태그 `v*.*.*`를 푸시하면 GitHub Actions가 테스트 후 npm trusted publishing으로 공개 배포합니다.
+`npm test`는 패키지, metadata, 문서 일관성과 변경된 여덟 스킬의 정적 라우팅 시나리오 48개를 검사합니다. 이 fixture는 모델을 실제 호출하거나 자동 trigger 정확도를 측정하지 않습니다.
+
+외부 출처와 라이선스 표기는 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)에 기록합니다. `v*.*.*` release tag를 push하면 GitHub Actions 검증 후 npm trusted publishing으로 패키지를 배포합니다.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,40 @@
+# Third-Party Notices
+
+## Matt Pocock Skills
+
+The JHSTE workflow set is independently maintained, but parts of the workflow structure and terminology in the following areas were informed by or adapted from the `mattpocock/skills` repository:
+
+- `jhste-grill`: one-question-at-a-time decision-tree interviews, environment-first fact gathering, continuous domain-document maintenance, and resolving consequential branches before stopping;
+- `jhste-domain-modeling`: immediate glossary updates, concrete scenario checks, lazy `CONTEXT.md` and ADR locations, and the three-part ADR threshold;
+- `jhste-to-spec`: conversation and codebase synthesis, behavioral test seams, and avoiding stale implementation recipes;
+- `jhste-diagnosing-bugs`: feedback-loop construction, falsifiable hypotheses, targeted instrumentation, regression verification, and cleanup;
+- `jhste-to-tickets`: tracer-bullet slices, blocking edges, bounded preparatory work, and expand-migrate-contract sequencing;
+- `jhste-coding`: module/interface/seam reasoning, caller-visible contracts, and avoiding shallow pass-through abstractions.
+
+Upstream reviewed at commit `ed37663cc5fbef691ddfecd080dff42f7e7e350d` and compared with the current `main` branch on 2026-07-25:
+
+- https://github.com/mattpocock/skills
+
+No upstream skill file is distributed verbatim. The full upstream MIT notice is retained because the resulting instructions adapt workflow structure and some terminology.
+
+### MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jhste-skills",
-  "version": "0.7.0",
-  "description": "A lean GPT-5.6-oriented engineering skill set for coding, pull request reviews and review follow-up, decision interviews, GitHub tickets, and domain modeling.",
+  "version": "0.8.0",
+  "description": "A lean GPT-5.6-oriented engineering skill set for coding, diagnosis, specifications, handoffs, implementation finalization, GitHub tickets, pull request review and follow-up, decision interviews, and domain modeling.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -13,10 +13,11 @@
     "README.md",
     "README.en.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "scripts": {
-    "test": "node scripts/validate-package.mjs"
+    "test": "node scripts/validate-package.mjs && node scripts/validate-routing-scenarios.mjs"
   },
   "engines": {
     "node": ">=18"

package/skills/jhste-coding/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jhste-coding
-description: Implement features, fix bugs, and refactor repository code with a small, contract-preserving change and relevant validation. Use when the requested outcome requires modifying code. Do not use for read-only analysis, planning, interviewing, issue creation, or domain documentation.
+description: Implement features, sufficiently understood bug fixes, and refactors with a small contract-preserving code change and relevant validation. Use when the requested outcome requires modifying repository code and the path to a correction is reasonably clear. For uncertain root-cause work, use jhste-diagnosing-bugs; for independently auditing and finishing an existing implementation, use jhste-implementation-finalizer. Do not use for read-only analysis, planning, interviewing, issue creation, domain documentation, or implementation finalization.
 ---
 
 # JHSTE Coding
@@ -16,17 +16,23 @@ Deliver the requested behavior with the smallest clear change that fits the repo
 - Relevant non-destructive validation passes, or the unverified surface and reason are reported.
 - Uncertain, partial, and failed states are not silently treated as success.
 
+## Frame the change
+
+Before editing, identify the requested outcome, material non-goals, caller-visible contract, and important failure states. Locate the module that owns the behavior and the seam through which callers or tests observe it. For a trivial change this can be a brief check; expand the analysis only when the change crosses boundaries or alters a contract.
+
 ## Working contract
 
-Inspect the affected code, repository guidance, and nearby patterns before editing. Reuse established boundaries and abstractions when they fit. Introduce a new abstraction only when the current change has real variation, repeated logic, or a concrete side-effect boundary that becomes clearer by doing so.
+Inspect the affected code, repository guidance, and nearby patterns before editing. Keep behavior that changes for the same reason together. Reuse established boundaries and abstractions when they fit.
+
+Introduce a new abstraction when the current change demonstrates real variation, repeated change, or a concrete side-effect boundary that becomes clearer by doing so. Prefer a bounded preparatory refactor only when it directly enables the requested behavior and can be reviewed and validated independently. Avoid pass-through wrappers, broad configuration objects, and extension points justified only by possible future use.
 
 Treat public return shapes, nullability, errors, side effects, ordering, and documented behavior as contracts. Validate external input at its entry boundary. Keep credentials, sessions, authorization data, and sensitive payloads out of logs and responses.
 
-For implementation requests, make in-scope local edits and run the narrowest useful validation without pausing for routine confirmation. Stop before an external write, destructive action, or material expansion of scope unless the user authorized it.
+For implementation requests, make in-scope local edits and run the narrowest useful validation without pausing for routine confirmation. Stop before an external write, destructive action, or material expansion of scope unless the user authorized it. When the root cause remains materially uncertain, avoid widening speculative edits and hand the investigation to `jhste-diagnosing-bugs`. When the starting point is a worker result, branch, diff, or partial implementation that must be independently audited and completed, use `jhste-implementation-finalizer` rather than treating its completion claim as evidence.
 
 ## Validation
 
-Choose checks that exercise the changed behavior: targeted tests first, then applicable type, lint, build, or smoke checks. Do not add a test at an artificial seam merely to claim coverage. Never imply that a check ran when it did not.
+Choose checks that exercise the changed behavior: targeted tests first, then applicable type, lint, build, or smoke checks. Add tests at a seam that represents the caller-visible behavior rather than creating an artificial seam to claim coverage. Re-read the final diff for scope creep, stale compatibility paths, and temporary instrumentation. Do not imply that a check ran when it did not.
 
 ## Final response
 

package/skills/jhste-diagnosing-bugs/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: jhste-diagnosing-bugs
+description: Diagnose difficult bugs and performance regressions whose cause or correct fix is uncertain, intermittent, environment-dependent, or spread across components. Use for explicit root-cause investigation that needs reproduction, competing hypotheses, instrumentation, or measurement. Do not use for an obvious typo, a direct compile or lint error, a known fix, CI inspection alone, or ordinary implementation.
+---
+
+# JHSTE Diagnosing Bugs
+
+## Goal
+
+Establish an evidence-backed root cause and, when a fix is in scope, prove that the smallest correction resolves the reported symptom without leaving diagnostic artifacts behind.
+
+## Frame the investigation
+
+Confirm the exact symptom, affected environment, expected behavior, known-good comparison, and whether the user requested diagnosis only or diagnosis plus a fix. Read repository guidance, relevant code, recent changes, tests, logs, traces, and operational evidence that are available.
+
+When the cause and correction are already clear, use `jhste-coding` instead. Route failing pull request checks to the repository's CI workflow unless the user is asking for a deeper root-cause investigation.
+
+## Build a useful feedback loop
+
+Prefer the shortest practical signal that exercises the reported behavior: an existing test, focused command, request replay, fixture, benchmark, profiler capture, or small harness. Run it when the environment permits and record the exact symptom it can detect.
+
+Tighten the loop when doing so materially improves speed, determinism, or fidelity. For intermittent failures, increase the reproduction rate and capture the conditions rather than claiming determinism that the evidence does not support. If no runnable loop is available, continue with the strongest captured artifact or observation available and state the resulting limit.
+
+## Reduce uncertainty
+
+Minimize the reproduction when that narrows the search without changing the failure. When more than one cause remains plausible, form at least two falsifiable hypotheses, rank them by inspected evidence, and choose probes that distinguish them. Change one material variable at a time where practical.
+
+Use targeted instrumentation at the boundaries that separate hypotheses. Tag temporary logs, flags, fixtures, or harnesses so they can be found and removed. For performance regressions, establish a comparable baseline and measure the affected path before choosing an optimization.
+
+## Fix and verify
+
+When a fix is requested, apply the smallest change that addresses the supported root cause. Add a regression test at a seam that reproduces the real failure pattern when such a seam exists. If the available seam would create false confidence, document that limitation and verify the original reproduction or measurement directly.
+
+Re-run the original signal after the fix, then run relevant nearby checks. Remove temporary instrumentation and throwaway artifacts unless the user asked to retain a clearly identified diagnostic aid. A need for temporary production instrumentation, changes to shared infrastructure, or writes to an external environment requires explicit authorization for that target.
+
+## Completion
+
+Report the reproduced symptom, evidence considered, hypotheses tested, supported root cause, change made if any, regression protection, commands or measurements run, diagnostic artifacts removed, and remaining uncertainty. Do not describe an unrun check as successful.

package/skills/jhste-diagnosing-bugs/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "JHSTE Diagnosing Bugs"
+  short_description: "Diagnose uncertain bugs with reproducible evidence"
+  default_prompt: "Use $jhste-diagnosing-bugs to reproduce this difficult failure, test competing causes, and verify the root-cause fix if one is requested."
+
+policy:
+  allow_implicit_invocation: true

package/skills/jhste-domain-modeling/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: jhste-domain-modeling
-description: Clarify domain terminology, concept boundaries, and relationships, and optionally maintain a project glossary or ADRs. Use when the user asks to define domain language, resolve conflicting terms, build a glossary, model domain concepts, or record a significant domain decision. Do not invoke for ordinary coding, generic architecture discussion, or incidental naming choices.
+description: Clarify domain terminology, concept boundaries, and relationships while continuously maintaining a project glossary and automatically recording qualifying ADRs. Use when the user asks to define domain language, resolve conflicting terms, build a glossary, model domain concepts, or record a significant domain decision. Do not invoke for ordinary coding, generic architecture discussion, or incidental naming choices.
 ---
 
 # JHSTE Domain Modeling
 
 ## Goal
 
-Establish precise shared language that matches the intended domain and the behavior implemented by the code.
+Establish precise shared language that matches the intended domain and the behavior implemented by the code, and keep the repository's domain documents synchronized as decisions settle.
 
 ## Investigate
 
@@ -17,17 +17,21 @@ Clarify one material concept at a time. Use concrete scenarios and edge cases to
 
 Keep the glossary free of implementation details. Keep specifications, task notes, and temporary decisions in their own artifacts.
 
-## Analyze versus write
+## Maintain the model continuously
 
-Analyze and propose changes by default. Edit `CONTEXT.md`, a repository-equivalent glossary, or an ADR only when the user asks to record, update, or apply the decisions. Follow the repository's existing location and format; create a new convention only with user authorization.
+In a writable repository, treat the domain-modeling request as authorization to maintain local glossary and ADR files. Follow the repository's existing locations and formats. If no convention exists, create `CONTEXT.md` at the root and `docs/adr/` lazily when the first corresponding entry is needed.
 
-Offer an ADR only when the decision is all three:
+When a term's meaning and boundary are agreed, test it with at least one concrete scenario. If no material contradiction remains, update the glossary immediately rather than waiting for the end of the session.
+
+Write an ADR immediately, without requesting separate confirmation, when the user selects a decision that is all three:
 
 - costly to reverse;
 - surprising without its rationale;
 - the result of a real trade-off between alternatives.
 
-Do not create an ADR for routine, temporary, or self-evident choices.
+Do not create an ADR for routine, temporary, self-evident, or still-unresolved choices. Follow the repository's ADR format. If none exists, use the next available `docs/adr/NNNN-<slug>.md` filename with `Status`, `Context`, `Decision`, `Alternatives considered`, and `Consequences` sections.
+
+If the user requests analysis only or forbids edits, present the exact proposed glossary and ADR changes instead. Do not commit, push, or publish repository changes without explicit authorization for those actions.
 
 ## Completion
 
@@ -36,5 +40,5 @@ Report:
 - terms added, changed, rejected, or still ambiguous;
 - scenarios used to test the model;
 - code or document mismatches found;
-- files changed, if writing was authorized;
-- ADR candidates and unresolved decisions that materially block the model.
+- glossary and ADR files changed;
+- unresolved decisions that materially block the model.

package/skills/jhste-domain-modeling/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "JHSTE Domain Modeling"
-  short_description: "Clarify domain terms, boundaries, and decisions"
-  default_prompt: "Use $jhste-domain-modeling to clarify the domain language and surface any conflicting concepts."
+  short_description: "Clarify terms and maintain glossary and ADRs"
+  default_prompt: "Use $jhste-domain-modeling to clarify the domain language and keep the project glossary and qualifying ADRs synchronized."
 
 policy:
   allow_implicit_invocation: true

package/skills/jhste-grill/SKILL.md

@@ -1,25 +1,37 @@
 ---
 name: jhste-grill
-description: Interview the user one decision at a time to sharpen or stress-test a plan, product behavior, or design. Use when the user asks to be interviewed, grilled, questioned, or guided through unresolved decisions. Do not invoke merely because an ordinary request has a small ambiguity.
+description: Interview the user one consequential decision at a time to sharpen or stress-test a plan, product behavior, or design while maintaining settled domain context and qualifying ADRs in the repository. Use when the user asks to be interviewed, grilled, questioned, or guided through unresolved decisions. Do not invoke merely because an ordinary request has a small ambiguity.
 ---
 
 # JHSTE Grill
 
 ## Goal
 
-Reach enough shared understanding for the user to make or delegate the next layer of work confidently.
+Reach shared understanding across every consequential decision branch so the user can make or delegate the next layer of work confidently.
 
 ## Interview
 
 Inspect available code, documents, and prior decisions instead of asking the user for discoverable facts. Ask about choices that belong to the user: desired behavior, scope, priorities, compatibility, failure behavior, and consequential trade-offs.
 
-Ask one decision question at a time. For each question, provide a recommended answer with its main reason and meaningful trade-off. Follow dependencies between decisions; do not explore branches that cannot affect the outcome.
+Ask one decision question at a time. For each question, provide a recommended answer with its main reason and meaningful trade-off. Follow dependencies between decisions.
 
-Challenge contradictions and unsupported assumptions directly. Preserve explicit user choices. Do not implement code, publish issues, or edit domain documents as part of this skill alone.
+Treat a branch as consequential when it can change the goal, success criteria, scope, user-visible behavior, compatibility, data or security behavior, recovery from failure, or a costly-to-reverse trade-off. Resolve every consequential branch or record it as an explicit blocker. Skip reversible preferences and implementation details that the next worker can decide safely.
+
+Challenge contradictions and unsupported assumptions directly. Preserve explicit user choices. Do not implement code or publish issues as part of this skill alone.
+
+## Maintain decision documents
+
+In a writable repository, treat the request to run this interview as authorization to maintain local domain and decision documents. Read the existing glossary, context map, ADRs, and repository conventions first. Follow their locations and formats. If the repository has no convention, create `CONTEXT.md` at the root and `docs/adr/` lazily when the first corresponding entry is needed.
+
+When a domain term's meaning and boundary are agreed, test it with at least one concrete scenario. If no material contradiction remains, update the glossary immediately before asking the next question. Keep implementation details, specifications, and temporary notes out of the glossary.
+
+When the user selects a decision that is costly to reverse, surprising without its rationale, and the result of a real trade-off, write an ADR immediately without requesting separate confirmation. Follow the repository's ADR format. If none exists, use the next available `docs/adr/NNNN-<slug>.md` filename with `Status`, `Context`, `Decision`, `Alternatives considered`, and `Consequences` sections.
+
+Keep documents synchronized throughout the interview rather than batching updates at the end. If the user requests analysis only or forbids edits, present the exact proposed glossary and ADR changes instead. Do not commit, push, or publish repository changes without explicit authorization for those actions.
 
 ## Stop condition
 
-Stop when the goal, success criteria, scope, important behavior, and material failure cases are clear enough for the intended next step. Do not continue into reversible preferences or implementation details that the next worker can decide safely.
+Stop when the goal, success criteria, scope, important behavior, consequential failure cases, and costly-to-reverse trade-offs are resolved or explicitly recorded as blockers. Do not continue into reversible preferences or implementation details that the next worker can decide safely.
 
 ## Outcome
 
@@ -29,4 +41,6 @@ Summarize only what the session established:
 - decisions and their reasons;
 - constraints and out-of-scope items;
 - unresolved questions that still block progress;
-- domain terms affected and ADR candidates, when material.
+- domain terms added or changed;
+- ADRs created;
+- documentation files changed.

package/skills/jhste-grill/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "JHSTE Grill"
-  short_description: "Sharpen plans through focused decision interviews"
-  default_prompt: "Use $jhste-grill to interview me one decision at a time and summarize what we decide."
+  short_description: "Resolve decisions and maintain context documents"
+  default_prompt: "Use $jhste-grill to interview me one consequential decision at a time, updating settled context and qualifying ADRs as we go."
 
 policy:
   allow_implicit_invocation: true

package/skills/jhste-handoff/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: jhste-handoff
+description: Create or update executor-neutral implementation handoff documents that preserve settled decisions, scope, ownership, progress, verification, blockers, and an exact resume point. Use when the user explicitly asks to hand work off, prepare implementation context for another worker or session, split long work into resumable phases, or refresh an existing handoff. Do not use for a specification, GitHub ticket graph, ordinary plan, implementation itself, or automatic worker orchestration.
+---
+
+# JHSTE Handoff
+
+## Goal
+
+Create the smallest durable work contract that lets another implementation mechanism continue without rediscovering material decisions or inventing product behavior.
+
+## Authority and boundaries
+
+An explicit request to create or update a handoff authorizes the corresponding local handoff documents. Respect analysis-only or no-edit requests. Commit, push, issue, pull-request, and other external writes still require authorization in the user's request.
+
+Keep the handoff independent of any agent, provider, model, CLI, branch strategy, or status protocol. Record the actual executor or workspace only as an execution fact when it helps coordination.
+
+A handoff records execution state; it is not a substitute for a specification, ADR, domain glossary, or GitHub issue graph. Link to those sources instead of copying them.
+
+## Inspect and settle the contract
+
+Read current user instructions, repository guidance, relevant specs, ADRs, domain context, issues, existing handoffs, code, tests, interfaces, current diff, and parallel ownership before writing.
+
+Do not invent paths, symbols, commands, or architecture. Resolve or visibly block decisions that would materially change behavior, scope, compatibility, data handling, failure recovery, destructive behavior, authorization, or a costly-to-reverse integration boundary. Use `jhste-grill` when a decision interview is needed. Leave repository-discoverable facts and reversible internal details to worker discretion.
+
+## Document set
+
+Follow an established repository handoff convention. When none exists, use:
+
+```text
+docs/handoff/indexes/<work-slug>.md
+docs/handoff/phases/<work-slug>-pNN-<phase-slug>.md
+```
+
+Create only the index when the work is one understandable and verifiable unit. Add phase documents only for multi-session or parallel work, independently verifiable outcomes, meaningful dependencies, distinct integration boundaries, or reliable partial resumption. Do not create one directory per work slug or permanent checkpoint and blocker directories.
+
+Keep the index as the short entry point. Record the objective, current state, phase-level progress, authoritative references, work ownership, decision and execution boundaries, cross-phase risks, and next entry point. Keep detailed tasks out of the index.
+
+Make each phase independently resumable. Record its outcome, status, entry criteria, in-scope and out-of-scope work, confirmed facts, working assumptions, worker discretion, measurable tasks, relevant locations, required behavior and edge cases, verification, exit criteria, next-phase deliverables, remaining risks, and exact resume point. Omit empty sections.
+
+## Parallel work and updates
+
+Do not treat an uncommitted tree or parallel workers as blockers by themselves. Record owned areas, shared contracts, integration owner, workspace or branch when known, and files that require serialized integration. Stop only when ownership cannot be distinguished, safe isolation is unavailable, or continuing would overwrite another workstream.
+
+Update the handoff at phase start, a material blocker or decision change, and phase completion. The active worker may update its phase; the coordinator or finalizer verifies completion and owns the index. Avoid per-edit documentation churn.
+
+## Completion
+
+Finish when the objective and scope are explicit, material decisions are settled or blocked, ownership and integration responsibility are clear, verification and exit criteria are measurable, the document set is no larger than necessary, and the next executor has one exact entry point.

package/skills/jhste-handoff/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "JHSTE Handoff"
+  short_description: "Create durable executor-neutral implementation handoffs"
+  default_prompt: "Use $jhste-handoff to create or update a compact implementation handoff with clear ownership, verification, and an exact resume point."
+
+policy:
+  allow_implicit_invocation: true

package/skills/jhste-implementation-finalizer/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: jhste-implementation-finalizer
+description: Independently audit, correct, verify, and finish an implementation already produced or partially produced and, when applicable, synchronize an existing handoff and complete already-authorized updates to the same pull request. Use when the user asks to take over, inspect and finish, finalize, or independently verify a branch, diff, worktree, worker result, or incomplete implementation. Do not use for an initial PR review, existing review-comment follow-up alone, ordinary implementation from scratch, CI-log diagnosis alone, or merging.
+---
+
+# JHSTE Implementation Finalizer
+
+## Goal
+
+Treat completion claims as unverified input. Determine whether the requested outcome is complete, correct, integrated, and ready to publish, then directly fix in-scope gaps instead of stopping at review comments.
+
+## Route the right work
+
+Use `jhste-coding` when no prior implementation needs an independent audit and the requested change is sufficiently understood. Use `jhste-diagnosing-bugs` when uncertain root cause or measurement is the primary work. Use `jhste-pr-review` for review-only findings and `jhste-review-followup` when existing review comments define the scope.
+
+Do not merge, enable auto-merge, resolve review threads, or make unrelated issue changes unless the user explicitly requests those actions.
+
+## Establish the contract
+
+Reconcile evidence in this order: current user instructions, repository guidance, current specs and ADRs, domain context and interfaces, related issues and acceptance criteria, handoff documents, tests and caller-visible behavior, then the worker report. Verify the handoff itself; correct it when stronger evidence or the implementation disproves it.
+
+Identify the repository, base, working branch or workspace, starting commit, complete task-owned diff, unrelated changes, parallel ownership, and shared integration points. An uncommitted tree is not a blocker when ownership and isolation are clear.
+
+For nontrivial work, map each material requirement to implementation and verification evidence in one compact table in the handoff or final report. Skip ceremony for a tiny change, but never mark a requirement complete from self-report alone.
+
+## Audit and finish
+
+Inspect the complete task-owned diff and relevant surrounding code, callers, tests, contracts, configuration, and documentation. Check for missing behavior, edge cases, partial integration, compatibility regressions, stale assumptions, weak tests, temporary artifacts, unnecessary abstraction, relevant performance or usability regressions, and accidental absorption of another workstream.
+
+Make one consolidated correction pass for related findings. Directly fix in-scope omissions, defects, integration gaps, regression coverage, stale handoff or documentation, temporary code, unnecessary complexity, and relevant performance or usability problems. Do not invent unresolved product policy, redesign another workstream's owned contract, or make unsettled destructive, migration, authentication, or authorization decisions.
+
+When a material decision remains unresolved after inspecting available evidence, record a compact blocker with the decision, consequence, evidence, options, recommendation, safe work completed, verification, and exact resume point.
+
+## Verify and synchronize
+
+Run focused verification in useful batches: changed-behavior tests first, then applicable regressions, type checks, lint, build, packaging, manual scenarios, and integration checks. Re-run affected checks after corrections. Record exact commands, results, skipped checks, and reasons; never claim an unrun check passed.
+
+Update an existing task handoff with actual implementation locations, requirement status, verification evidence, completed and remaining work, ownership, risks, and the exact next entry point or final completion state. Do not create a new handoff merely because this skill ran unless the user also requested one.
+
+## Publish when authorized
+
+When the user's request already authorizes commit, push, or updating an existing pull request, inspect the final diff, keep unrelated changes out, commit intentionally, push the correct head branch, and update that same pull request's title and body to match the actual scope, validation, limitations, and risks. Never create a duplicate pull request when an existing one was named.
+
+## Completion
+
+Finish only when every material requirement has a traceable status, the complete task-owned diff has been inspected, in-scope gaps are corrected, relevant verification passed or has an honest limitation, parallel ownership remains intact, the handoff reflects reality when present, and authorized publication is complete.

package/skills/jhste-implementation-finalizer/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "JHSTE Implementation Finalizer"
+  short_description: "Audit, correct, verify, and finish worker implementations"
+  default_prompt: "Use $jhste-implementation-finalizer to independently audit this implementation, fix in-scope gaps, verify it, and complete already-authorized publication steps."
+
+policy:
+  allow_implicit_invocation: true

package/skills/jhste-to-spec/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: jhste-to-spec
+description: Synthesize an already discussed or otherwise defined engineering change into a decision-grounded specification using relevant repository evidence. Use when the user asks for a spec, PRD, design brief, or written behavior contract. Do not use to interview unresolved requirements, create execution handoffs, split work into tickets, implement code, or publish an artifact unless the user requests that write.
+---
+
+# JHSTE To Spec
+
+## Goal
+
+Produce a reviewable specification that separates established decisions from unresolved questions and gives the next worker observable behavior to preserve.
+
+## Resolve the evidence
+
+Read the relevant conversation, referenced artifacts, repository guidance, glossary or ADRs, current code, and nearby tests or contracts. Use repository vocabulary where it is established. Treat code as evidence of the current state rather than proof that the current state is intended.
+
+Ask only when a missing decision would materially change the requested outcome. When useful progress is still possible, draft with the uncertainty named instead of inventing an answer. Route a decision interview to `jhste-grill` and domain-language conflicts to `jhste-domain-modeling`.
+
+## Write the specification
+
+Choose sections that fit the work rather than forcing every change into user stories. Cover the following information when it is material:
+
+- problem and desired outcome;
+- observable behavior, caller contracts, failure behavior, and compatibility constraints;
+- decisions already made and the reason for consequential choices;
+- validation strategy and the existing highest useful seam that can demonstrate the behavior;
+- scope boundaries and explicit non-goals;
+- unresolved questions, assumptions, and external dependencies.
+
+Prefer behavioral language over an implementation recipe. Mention modules, interfaces, schemas, or integration points when they record a real decision. Avoid speculative file paths and code snippets that are likely to become stale; include a compact prototype-derived shape only when it preserves a decision more precisely than prose.
+
+## Draft versus write
+
+Return a draft in the conversation by default. A request to create, record, or publish the specification authorizes only that artifact in the repository or issue tracker the user identified. Follow the repository's existing document location, issue shape, and label policy; do not invent a new convention or label.
+
+Writing a specification does not authorize code changes or implementation tickets. When the user wants an executable issue graph after the specification is ready, use `jhste-to-tickets`. When the user wants durable progress, ownership, verification, and resume state for another executor, use `jhste-handoff`; do not turn the specification into a work tracker.
+
+## Completion
+
+Before finishing, check that each asserted requirement is supported by the conversation or inspected evidence, unresolved decisions remain visibly unresolved, validation describes observable behavior, and the next step is clear. Report any material repository surface that could not be inspected.

package/skills/jhste-to-spec/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "JHSTE To Spec"
+  short_description: "Synthesize settled decisions into a reviewable spec"
+  default_prompt: "Use $jhste-to-spec to turn the established decisions and repository evidence into a reviewable engineering specification."
+
+policy:
+  allow_implicit_invocation: true

package/skills/jhste-to-tickets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jhste-to-tickets
-description: Turn a defined plan, specification, or conversation into GitHub parent and sub-issues with acceptance criteria and native dependency relationships. Use when the user asks to draft, split, organize, or publish work as GitHub issues or tickets. Do not use for ordinary planning or work whose execution path still requires major investigation.
+description: Turn a defined plan, specification, or conversation into GitHub parent and sub-issues with acceptance criteria and native dependency relationships. Use when the user asks to draft, split, organize, or publish established work as GitHub issues or tickets. Do not use for ordinary planning, local execution handoffs, unresolved product behavior, or work whose execution path still requires major investigation.
 ---
 
 # JHSTE To Tickets
@@ -11,7 +11,9 @@ Create a GitHub-native work graph whose ready issues can be claimed and complete
 
 ## Resolve context
 
-Identify the GitHub repository from the request or current remote. Read any referenced issue, specification, conversation context, repository guidance, and relevant code. Ask only for a missing decision that would materially change scope, issue boundaries, or dependencies.
+Identify the GitHub repository from the request or current remote. Read any referenced issue, specification, conversation context, repository guidance, glossary or ADRs, and enough relevant code and tests to understand current seams, compatibility constraints, and verification paths. Ask only for a missing decision that would materially change scope, issue boundaries, or dependencies.
+
+If the desired behavior is not yet settled, hand the request to `jhste-grill` or `jhste-to-spec` rather than encoding guesses as tickets. If the main uncertainty is the root cause of a failure, use `jhste-diagnosing-bugs` before planning implementation work. When the requested artifact is a durable local record of ownership, phase progress, verification, blockers, and an exact resume point, use `jhste-handoff` instead of duplicating that state across issues.
 
 ## Draft the work graph
 
@@ -27,7 +29,7 @@ Split implementation into tracer-bullet issues. Each issue must:
 
 Do not create separate database, API, UI, and test issues when none delivers behavior alone. Do not split work that is already safe and reviewable as one issue.
 
-For a wide mechanical change that cannot land green as vertical slices, use expand-migrate-contract: introduce the compatible form, migrate bounded batches, then remove the old form.
+Create a separate preparatory issue only when a bounded refactor or compatibility step is required before a useful vertical slice can land green. State the constraint it removes and keep generic cleanup in the slice that needs it. For a wide mechanical change that cannot land green as vertical slices, use expand-migrate-contract: introduce the compatible form, migrate bounded batches, then remove the old form.
 
 Add a dependency only when the blocked issue cannot start until the blocker completes. Convenience or preferred order is not a dependency. The open, unblocked issues form the execution frontier.
 
@@ -37,7 +39,7 @@ Draft by default. Present the parent, sub-issues, and dependency edges without w
 
 Publish when the user explicitly asks to create, post, or publish the issues. That request authorizes these GitHub writes; it does not authorize unrelated repository changes. Create the parent and sub-issues, use GitHub's native parent and blocked-by relationships, then return their links and the initial frontier.
 
-When native relationships are unavailable, report the limitation before falling back to references in issue bodies.
+Follow the repository's existing label policy or labels named by the user. Do not invent or automatically apply `ready-for-agent` or another workflow label. When native relationships are unavailable, report the limitation before falling back to references in issue bodies.
 
 ## Issue shape
 
@@ -61,4 +63,4 @@ Avoid speculative file paths, implementation recipes, and code snippets that wil
 
 ## Completion
 
-Before finishing, verify that every issue has a clear outcome, every dependency is necessary, and at least one frontier issue exists unless an explicit external blocker prevents all work.
+Before finishing, verify that every issue has a clear outcome, every preparatory issue is necessary, every dependency is a real blocker, labels follow an established policy, and at least one frontier issue exists unless an explicit external blocker prevents all work.