akiojin/gwt-spec-clarify
plugins/gwt/skills/gwt-spec-clarify/SKILL.md
Clarify an existing `gwt-spec` by resolving `[NEEDS CLARIFICATION]` markers, tightening user stories, and locking acceptance scenarios before planning. Use directly or through `gwt-spec-ops`.
$ install --global
skillsauthnpx skillsauth add akiojin/gwt gwt-spec-clarifyInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 2, 2026, 3:53 PM56.2s1 file scanned
SKILL.md
- name:
- gwt-spec-clarify
- description:
- Clarify an existing `gwt-spec` by resolving `[NEEDS CLARIFICATION]` markers, tightening user stories, and locking acceptance scenarios before planning. Use directly or through `gwt-spec-ops`.
gwt SPEC Clarify
Use this skill to turn a draft spec.md artifact into a planning-ready specification.
gwt-spec-clarify is a focused clarification step inside the wider SPEC workflow.
- If the target SPEC does not exist yet, use
gwt-spec-registerfirst. - If no important clarification remains, return a planning-ready result to
gwt-spec-ops. - Do not generate
plan.mdortasks.mdhere.
Artifact contract
This skill works on the spec.md issue comment artifact:
<!-- GWT_SPEC_ARTIFACT:doc:spec.md -->
doc:spec.md
spec.md must contain these sections:
- Background
- User Stories
- Acceptance Scenarios
- Edge Cases
- Functional Requirements
- Non-Functional Requirements
- Success Criteria
Unknown decisions must be written as [NEEDS CLARIFICATION: question].
Workflow
-
Resolve the target SPEC.
- Accept a
gwt-specissue number or a request that already has a known destination. - If the destination is unknown, use
gwt-issue-searchfirst.
- Accept a
-
Read the current
spec.mdartifact.- If it does not exist, seed it through
gwt-spec-register, then continue.
- If it does not exist, seed it through
-
Find clarification gaps.
- Prioritize
[NEEDS CLARIFICATION]markers. - Also look for missing user stories, weak acceptance scenarios, vague requirements, and unstated edge cases.
- Prioritize
-
Resolve what is knowable before asking.
- Fill obvious gaps from the source Issue, existing comments, current implementation, and surrounding artifacts.
- Ask only high-impact questions that change scope, behavior, or testability.
- Ask at most 5 questions, ordered by implementation impact.
-
Update the
spec.mdartifact.- Replace resolved markers with concrete decisions.
- Keep unresolved blockers explicit.
- Tighten user stories and acceptance scenarios while preserving existing intent.
-
Decide the next step.
- If a real product or scope decision remains, stop with a blocker summary.
- If the remaining gaps are implementation-local and can be decided safely, resolve them here.
- If the spec is planning-ready, return control to
gwt-spec-opsor proceed togwt-spec-plan.
Planning-ready exit criteria
The spec may move to planning only when all of the following are true:
- No critical
[NEEDS CLARIFICATION]markers remain - Each user story has at least one acceptance scenario
- Edge cases are explicit where implementation could diverge
- Functional and success criteria are testable
Recommended output
## Clarification Report: #<number>
Resolved: <N>
Remaining blockers: <M>
Next: `gwt-spec-ops` -> `gwt-spec-plan` | ask follow-up clarification
Operations
Read current spec.md
python3 "${CLAUDE_PLUGIN_ROOT}/skills/gwt-spec-ops/scripts/spec_artifact.py" \
--repo "." \
--issue "<number>" \
--get \
--artifact "doc:spec.md"
Update spec.md
python3 "${CLAUDE_PLUGIN_ROOT}/skills/gwt-spec-ops/scripts/spec_artifact.py" \
--repo "." \
--issue "<number>" \
--upsert \
--artifact "doc:spec.md" \
--body-file /tmp/spec.md
Related Skills
akiojin/tui-design
tools
VerifiedTrustedCommunity
Create distinctive, production-grade terminal user interfaces. Use when building TUI components with ratatui, CLI output styling, or xterm.js terminal rendering. Triggers: 'design TUI', 'terminal UI', 'TUIデザイン', 'ターミナルUI', 'ratatui widget'
3SKILL.mdUpdated Apr 15, 2026
akiojin/gwt-spec-search
testing
VerifiedTrustedCommunity
Semantic search over SPEC Issues (GitHub Issue cache at ~/.gwt/cache/issues/) using vector embeddings. Use when searching for existing specs, finding related specs, checking for duplicate specs, or determining which spec owns a scope. Mandatory preflight before gwt-discussion when the work may need a SPEC owner. Use when user says 'search specs', 'find related specs', 'check for duplicate specs', or asks which spec owns a scope.
3SKILL.mdUpdated Apr 15, 2026
akiojin/gwt-search
testing
VerifiedTrustedCommunity
Mandatory preflight before gwt-discussion, gwt-register-issue, and gwt-fix-issue. Use proactively before creating any SPEC or Issue owner or before reusing an existing one. Searches SPEC Issues, GitHub Issues, and project files via ChromaDB. Triggers: 'search', 'find related', 'check duplicates'.
3SKILL.mdUpdated Apr 15, 2026
akiojin/gwt-register-issue
business
VerifiedTrustedCommunity
Use when the user wants to register new work from a bug report, idea, or task description and an existing GitHub Issue number is not already known.
3SKILL.mdUpdated Apr 15, 2026