菜单
Refine and plan a GitHub issue for implementation. Reads the issue, explores the codebase, creates a UX mockup if needed, writes a step-by-step implementation plan, and updates the issue body.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Conduct a structured bug investigation and post-mortem analysis. Traces the root cause of production bugs, verifies deployment status, analyzes logs, identifies guardrail gaps, and produces actionable artifacts (bug fix issue + guardrail updates).
Execute a list of GitHub issues sequentially. Scans issues upfront, refines as needed, implements each one, creates PRs, and merges them in order.
Create or update a pull request. Use when the user wants to create a PR, submit changes for review, or merge their work. Handles git operations, tests, CI monitoring, and PR creation.
Add a feature notification to announce new features, improvements, or bug fixes to users. Use when the user wants to broadcast a change, add a notification, or announce a new feature after completing work on a PR.
| name | refine |
| description | Refine and plan a GitHub issue for implementation. Reads the issue, explores the codebase, creates a UX mockup if needed, writes a step-by-step implementation plan, and updates the issue body. |
You are refining a GitHub issue into an actionable implementation plan. The argument is the issue number (e.g., /refine 336).
gh issue view <number>
Read the full issue body. Extract:
Before exploring code, evaluate whether the issue is clear enough to plan:
Ask clarifying questions if:
Proceed without asking if:
Use AskUserQuestion to gather answers before continuing. Frame questions with specific options when possible.
Look for a mockup in mockups/ that matches the issue:
ls mockups/ | grep -i <feature-keyword>
If a mockup exists AND has a chosen design: Read the mockup file, note the chosen option, and incorporate it into the plan.
If a mockup exists but NO design is chosen: Read it, then ask the user which option they prefer before proceeding.
If NO mockup exists AND the issue involves UI changes: Create one (see Step 4).
If NO mockup exists AND the issue is backend-only: Skip to Step 5.
Create a standalone HTML mockup file at mockups/<feature-name>.html with 10 distinct design options.
Follow the exact pattern used in existing mockups. Key requirements:
Use the project's semantic color tokens — copy the CSS variable blocks from an existing mockup (e.g., tag-hub-usage-counts.html). The theme uses Nord palette colors with light/dark mode via [data-theme="dark"].
Include these standard elements:
https://cdn.tailwindcss.com)https://unpkg.com/primeicons@7.0.0/primeicons.css)toggleTheme() scriptFor each option include:
#a3be8c for pros, red #bf616a for cons)Mark one option as "Recommended" with:
border: 2px solid #a3be8c)Include a comparison table at the bottom summarizing all options across key dimensions.
Include a "Recommendation" section explaining the recommended choice.
<!-- Copy the <head> section from an existing mockup for theme setup -->
<!-- Each option follows this pattern: -->
<div class="option-card mb-8"> <!-- Add class="recommended" for the recommended option -->
<div class="option-header">
<div class="flex items-center gap-3">
<div class="option-number">1</div>
<div>
<div class="text-foreground text-sm font-semibold">Option Title</div>
<div class="text-foreground-muted text-xs">Short description</div>
</div>
</div>
<!-- Only on recommended: <div class="recommended-badge">Recommended</div> -->
</div>
<div class="option-body">
<!-- Visual mockup content -->
<div class="pros-cons">
<div class="pro">+ Advantage</div>
<div class="con">- Disadvantage</div>
</div>
</div>
</div>
<div class="option-divider"></div>
After creating the mockup, open it for the user:
open mockups/<feature-name>.html
Then tell the user: "I've created a mockup with 10 design options and recommended Option X. Please review and let me know which option you prefer, or I'll proceed with the recommended one."
Wait for the user's response before continuing.
Thoroughly explore all code relevant to the issue. Be exhaustive — missing a file here means a broken plan.
Backend (always check all of these):
src/PraxisNote.Domain/Aggregates/)src/PraxisNote.Infrastructure/Persistence/Repositories/)src/PraxisNote.Application/Features/)src/PraxisNote.Web/Endpoints/)Frontend (always check all of these):
*.model.ts)*.service.ts)*.page.ts)*.component.ts)Cross-cutting (always check):
increment/decrement/update calls on services)tests/ directory)# Find relevant files by keyword
grep -r "MethodName" src/ --include="*.cs" --include="*.ts" -l
# Find all callers of a method
grep -r "methodName" src/ --include="*.ts" -l
# Check for existing tests
grep -r "ClassName" tests/ --include="*.cs" -l
# Understand the domain model
cat src/PraxisNote.Domain/Aggregates/<Entity>/<Entity>.cs
Read the full contents of every relevant file. Don't just find file names — read the actual code to understand:
When writing a new repository method, always check existing repository implementations for established patterns before writing code. EF Core has LINQ translation limitations that are easy to get wrong.
# Find existing repository methods that do similar operations
grep -r "Contains\|ToList\|ToHashSet\|ToLower" src/PraxisNote.Infrastructure/Persistence/Repositories/ --include="*.cs" -B 2 -A 5
Common mistakes to avoid:
HashSet<T>.Contains() is NOT translatable to SQL — use List<T>.Contains() (generates IN (...)).ToLowerInvariant() is NOT translatable — use .ToLower() (generates LOWER())TagIds as HashSet<Guid>) cannot be queried with .Contains() in LINQ — must filter in-memory after loadingReference: See MeetingRepository.cs:70 for the correct pattern. See bug #642 for what happens when these rules are violated.
When the plan involves integrating a UI library or extension, identify the actual DOM output by reading the library's source code or documentation. Do NOT assume standard HTML elements — many libraries (TipTap, ProseMirror, Slate, etc.) use custom NodeViews that render non-standard DOM structures. Include the actual DOM structure in the plan so CSS selectors, query selectors, and interaction logic are correct from the start.
Write a concrete, step-by-step implementation plan with:
Each step must include:
TaskRepository.GetTagUsageCountsAsync at line 28-42")These requirements ensure sub-agents can implement the plan without ambiguity or missed updates.
For any method being created or modified, the plan must include the full method signature — not just the file path. This prevents sub-agents from guessing parameter types, return types, or method names.
**Method signature:**
\`\`\`csharp
// New method in ITaskRepository
Task<IReadOnlyList<TaskItem>> GetByDueDateRangeAsync(Guid userId, DateOnly from, DateOnly to, CancellationToken ct = default);
\`\`\`
\`\`\`typescript
// New method in task.service.ts
loadByDueDateRange(from: string, to: string): void
\`\`\`
Do NOT write vague instructions like "add a method to get tasks by date range" — show the exact signature.
For any method being changed (signature, behavior, or return type), the plan must identify all call sites by running grep and listing the results. Sub-agents must not discover missing callers mid-implementation.
**Callers of `TaskRepository.GetByStatusAsync` (must be updated):**
- `src/PraxisNote.Application/Features/Tasks/GetUserTasks.cs:34`
- `src/PraxisNote.Application/Features/Summary/GetDailySummary.cs:58`
- `src/PraxisNote.Web/ClientApp/src/app/tasks/task.service.ts:42`
If a method has zero callers (new method), state that explicitly: "No existing callers — this is a new method."
For UI changes, show the exact HTML being modified with before and after snippets. Do not write "update the template to show the new field" — show the actual markup.
**Before** (from `tasks.page.ts` template, lines 45-52):
\`\`\`html
<div class="flex items-center gap-2">
<span class="text-sm text-foreground">{{ task.title }}</span>
</div>
\`\`\`
**After:**
\`\`\`html
<div class="flex items-center gap-2">
<span class="text-sm text-foreground">{{ task.title }}</span>
@if (task.dueDate) {
<span class="text-xs text-foreground-muted">{{ task.dueDate | date }}</span>
}
</div>
\`\`\`
Explicitly name shared components (with file paths) that the implementation should use, and warn against creating duplicates. Check src/app/shared/components/ and src/app/shared/services/ before planning any new shared utility.
**Shared components to reuse:**
- `src/app/shared/components/error-state.component.ts` — use for API error display
- `src/app/shared/components/delete-confirm-button.component.ts` — use for inline delete
- `src/app/shared/services/toast.service.ts` — use for mutation success/error feedback
**Do NOT create:** A new error display component, toast wrapper, or confirmation dialog — these already exist.
Append this machine-readable checklist to the end of every refined issue body. Every box must be checked before the issue is considered fully refined.
## Pre-Flight Checklist
- [ ] All callers of modified methods identified
- [ ] Shared components listed (or confirmed none apply)
- [ ] Template HTML before/after included (for UI changes)
- [ ] Method signatures specified for new/modified methods
- [ ] Verification steps defined for each acceptance criterion
- [ ] Optimistic update impact assessed
- [ ] E2E test decision documented (add/skip with reason)
- [ ] New API calls use correct HTTP client (`HttpClient` for critical CRUD, `fetch()` for non-critical — see CLAUDE.md "Auth Interceptor")
If a checklist item does not apply (e.g., "Template HTML" for a backend-only change), check it and add "N/A — backend only".
Each acceptance criterion must have a concrete verification contract describing exactly what to navigate to, interact with, and assert during browser validation. This replaces vague criteria like "the feature works" with testable steps.
## Acceptance Criteria
- [ ] Tasks can be filtered by due date range
- **Verify:** Navigate to `/tasks`. Click the date filter. Select "This Week". Assert that only tasks with due dates in the current week are visible. Clear the filter. Assert all tasks reappear.
- [ ] Due date badge shows correct color
- **Verify:** Create a task with due date = today. Navigate to `/tasks`. Assert the due date badge has class `text-danger`. Create a task with due date = next week. Assert the badge has class `text-foreground-muted`.
## Implementation Plan
### Step 1 — [Area]: [What]
**Files:**
| File | Change |
|------|--------|
| `path/to/file.cs` | Description of change |
**Method signatures** (new/modified):
\`\`\`csharp
Task<Result> NewMethodAsync(Guid userId, string title, CancellationToken ct = default);
\`\`\`
**Callers** (for modified methods):
- `path/to/caller1.cs:34` — update to pass new parameter
- `path/to/caller2.ts:58` — update return type handling
**Shared components to reuse:**
- `src/app/shared/components/error-state.component.ts` — for error display
**Pattern to follow** (from `path/to/existing.cs:28-42`):
\`\`\`csharp
// Existing code that shows the pattern
\`\`\`
**Template before/after** (for UI steps):
\`\`\`html
<!-- Before (line 45-52) -->
<div>...</div>
<!-- After -->
<div>...updated...</div>
\`\`\`
**New code:**
\`\`\`csharp
// The actual code to write
\`\`\`
### Step 2 — ...
After completing the implementation plan, assess whether the feature warrants E2E test coverage.
Propose a test if the feature involves:
Do NOT propose tests for:
If no tests meet the evaluation criteria, skip this step entirely — don't ask about tests that aren't worth writing.
For each candidate E2E test, use AskUserQuestion to present it individually:
Question: "Should we add this E2E test?"
Header: "E2E Test"
Options:
- "Yes" — Include this test in the implementation plan
- "No" — Skip this test
- (User can also select "Other" to describe modifications)
Description for the question should include:
- Test name (e.g., "can insert and interact with toggle section")
- Test file (e.g., smoke-tests/note-editor.spec.ts)
- What it exercises (e.g., "Insert toggle via slash command → verify div[data-type='details'] renders → click toggle button → verify content shows/hides")
- Why it's valuable (e.g., "Would have caught #493 — third-party NodeView mismatch")
Present tests one at a time, waiting for the user's response before presenting the next. This ensures each test gets individual consideration rather than being rubber-stamped as a batch.
After writing the plan, update the issue labels:
to-refine labelrefined labeltag-hub, bug)gh issue edit <number> --remove-label "to-refine" --add-label "refined"
Replace the issue body with the refined version. Preserve the original sections (Overview, Dependencies, Chosen Design) and add/overwrite the Implementation Plan section.
Use gh issue edit with a heredoc:
gh issue edit <number> --body "$(cat <<'ISSUE_BODY'
## Overview
[preserved from original]
## Dependencies
[preserved from original]
## Chosen Design
[preserved or updated based on mockup selection]
---
## Implementation Plan
### Step 1 — ...
[the full plan]
---
## Acceptance Criteria
[preserved or refined from original — each criterion includes a verification contract]
---
## Pre-Flight Checklist
- [ ] All callers of modified methods identified
- [ ] Shared components listed (or confirmed none apply)
- [ ] Template HTML before/after included (for UI changes)
- [ ] Method signatures specified for new/modified methods
- [ ] Verification steps defined for each acceptance criterion
- [ ] Optimistic update impact assessed
- [ ] E2E test decision documented (add/skip with reason)
- [ ] New API calls use correct HTTP client (`HttpClient` for critical CRUD, `fetch()` for non-critical — see CLAUDE.md "Auth Interceptor")
ISSUE_BODY
)"
Tell the user: