OpenSpec Project Walkthrough – Refactoring Review, Enhancing Verify, and Building the First Tool

Problem

The review stage in the OpenSpec workflow includes a fifth dimension called Task Granularity that attempts to assess tasks.md. However, tasks.md is generated only after the review step (dependency chain: proposal → specs → design → review → tasks). The review schema ( openspec/schemas/with-review/schema.yaml) lists requires: proposal, specs, design and does not depend on tasks, so the review cannot actually inspect task granularity.

Refactor Plan (Three Actions)

Review instruction redesign : Reduce dimensions from five to four and replace the “Task Granularity” dimension with a “Split‑direction guidance” section that provides pre‑split suggestions for the soon‑to‑be‑generated tasks.md.

Verify SKILL.md enhancement : Add a fourth dimension named Task Granularity that checks task format, TDD compliance, code completeness, and effort‑estimate granularity.

Implement the first tool component : Build a pure‑frontend text-summary tool (proposal, design, specs, review, tasks) and verify the whole refactor.

Review Instruction Refactor

instruction: |
  从四个维度审查 proposal、specs 和 design 的完整性和质量。
  为即将生成的 tasks.md 提供拆分方向和优先级建议。

审查维度：
1. **边界条件**：Spec 是否覆盖 null、空值、越界等异常场景
2. **回滚方案**：变更是否包含回滚策略（数据库迁移、API 变更等）
3. **测试覆盖**：Design 是否明确了需要测试的场景和用例
4. **向后兼容**：是否分析了现有接口和数据的兼容性影响

输出格式：
- 每个维度给出明确状态：✅通过 / ⚠️警告 / ❌失败
- 警告和失败必须给出具体建议
- 给出整体评估 + 对 tasks 拆分的具体建议（分组、优先级、粒度标准）

注意：本审查在 tasks.md 生成之前执行，不能声称已审查 tasks.md。

Verify SKILL.md Enhancement

**Task Granularity**: Track task format compliance, TDD adherence, code completeness, and granularity assessment
- Task format: Verify each task uses `### 任务 N` with file list and TDD five‑step structure
- TDD compliance: Verify each task follows RED/GREEN/REFACTOR rhythm
- Code completeness: Verify no TBD/TODO placeholders exist
- Granularity assessment: Evaluate if each task's estimated effort falls within 2‑5 minute range

Review Template Update

## 整体评估

**拆分方向建议**：

**优先级排序**：

**粒度标准**：

Before/After Comparison

Review instruction : 5 dimensions (including task granularity) → 4 dimensions + split‑direction guidance

Verify SKILL.md : 3 dimensions (Completeness/Correctness/Coherence) → 4 dimensions (adds Task Granularity)

Review template : 5‑dimension template → 4‑dimension template

The refactor does not depend on a specific front‑end or back‑end; it applies to any OpenSpec workflow.

Implementing the Text‑Summary Tool

The AI generated the following artifacts under openspec/changes/implement-text-summary/:

| Artifact      | Description                                          |
|----------------|------------------------------------------------------|
| proposal.md   | Change proposal: pure‑frontend text‑summary tool      |
| design.md      | Design: summarization algorithm, component structure, state management |
| specs/text-summary/spec.md | 5 requirements, 15 scenarios |
| review.md      | Four‑dimension review (no task granularity)          |
| tasks.md       | 5 task groups covering stop‑words, sentence extraction, algorithm, UI, full verification |

Generated task groups:

Stop‑words list ( stopwords.ts, stopwords.test.ts)

Sentence extraction tool ( text-utils.ts, text-utils.test.ts)

Core summarization algorithm ( extract-summary.ts, extract-summary.test.ts)

UI component ( index.tsx, index.test.tsx)

Full verification (all 22 tests passing)

Build output:

> tsc -b && vite build
vite v8.0.12 building client environment for production...
✓ 1757 modules transformed.
dist/index.html 0.46 kB │ gzip: 0.30 kB
dist/assets/index-8W2XdHU1.css 20.28 kB │ gzip: 4.75 kB
dist/assets/text-summary-DP5GMCjc.js 2.83 kB │ gzip: 1.39 kB
dist/assets/index-CDtkiTKN.js 295.14 kB │ gzip: 94.33 kB
✓ built in 190ms

Verification of the Enhanced Verify

The verification report after applying the change showed only the original three dimensions:

## Verification Report: implement-text-summary
| Dimension    | Status                     |
|--------------|----------------------------|
| Completeness | 24/24 tasks complete       |
| Correctness  | 5/5 requirements implemented |
| Coherence    | Design followed            |

Analysis of why the new Task Granularity dimension did not appear:

Skill guidance ≠ hard constraint : .claude/skills/openspec-verify-change/SKILL.md is only a reference; the AI fell back to the familiar three‑dimension pattern.

Internal contradiction : Line 46 declares “four dimensions”, but later sections still mention “three dimensions”, causing the AI to prefer the more specific old wording.

Missing output format : The final assessment template was not updated, so the AI generated the old three‑dimension output.

Lesson: changing SKILL.md alone does not change AI behaviour; all related templates and fallback sections must be synchronized.

Lazy‑Loading Bug in the Browser

Despite a successful build and passing tests, opening http://localhost:5173/tools/text-summary displayed only the Suspense fallback “加载中…”. The cause was that router/index.tsx loaded the tool with React.lazy(), which requires a default export, but src/modules/text-summary/index.tsx exported the component as a named export: export function TextSummaryPage() { /* ... */ } Because there was no default export, the lazy component could not be resolved.

Fix Attempts

Added export default TextSummaryPage; – module loaded but React still did not resolve the component.

Moved the lazy call inside the component and wrapped with useMemo – ineffective.

Final solution : Replace React.lazy() with a manual dynamic import using useEffect + import() and store the default export in state.

// router/index.tsx final fix
const toolModules: Record<string, () => Promise<{ default: React.ComponentType<any> }>> = {
  'text-summary': () => import('/src/modules/text-summary/index.tsx'),
};

function ToolPage({ toolId }: { toolId: string }) {
  const [Component, setComponent] = useState<React.ComponentType<any> | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const loader = toolModules[toolId];
    if (!loader) { setError(`Tool not found: ${toolId}`); return; }
    loader()
      .then(mod => setComponent(() => mod.default))
      .catch(e => setError(e.message));
  }, [toolId]);

  if (error) return <div className="p-4">Error: {error}</div>;
  if (!Component) return <div className="p-4">加载中...</div>;
  return <Component />;
}

After this change the page rendered correctly (title, input area, length selector, generate button).

Post‑Fix Verification

All tests still pass (52 tests, including 22 new ones). The build output remains unchanged, and the lazy‑loading issue is resolved at runtime.

Archive

**Archive Complete**
Change: implement-text-summary
Schema: with-review
Archived to: openspec/changes/archive/2026-05-19-implement-text-summary/
Summary:
- 5 artifacts (proposal, design, specs, review, tasks) all done
- 24/24 tasks completed with TDD workflow
- Delta specs synced to main specs during apply
- Implementation in src/modules/text-summary/ (4 source files + 4 test files, 22 tests passing)

Git Push

The AI attempted to push but hit a network timeout (443). The user manually executed git push to complete the push.

Lessons Learned

Three‑layer refactor forms a closed loop : Template and review changes work, but verify’s new dimension failed because of SKILL inconsistencies.

Review should provide guidance, not post‑hoc verification : Removing dimension 5 turns review into a proper pre‑step.

Verify changes require synchronized templates and no contradictory statements.

Build + test ≠ runtime correctness. The lazy‑loading bug was invisible to static analysis and unit tests.

Never trust AI’s completion report blindly. Manual browser verification uncovered the hidden issue.

Related Resources

GitHub repository: https://github.com/shuge-x/shuge-ai-toolbox