Write Plan
Overview
Produce a complete, self-contained implementation plan that can be executed by
execute-plan
with minimal ambiguity.
This skill is for planning only:
Do not implement code
Do not modify production files (except plan artifacts)
Artifact Conventions
Use one consistent artifact structure for every plan:
Plan directory:
docs/plans/YYMMDD-HHmm-/
Main summary:
docs/plans/YYMMDD-HHmm-/SUMMARY.md
Phase files:
docs/plans/YYMMDD-HHmm-/phase-01-.md
,
phase-02-.md
, etc.
Optional research notes:
docs/plans/YYMMDD-HHmm-/research/.md
Use timestamp commands from the shared General Principles for folder and document timestamps.
Workflow
Step 1: Contextualize
Load project context per the shared Context Loading Protocol. Then inspect only the code areas relevant to the requested change.
Capture:
Existing patterns to follow
Constraints and dependencies
Risks, assumptions, and unknowns
Step 2: Initialize Plan Artifacts
Create:
docs/plans/YYMMDD-HHmm-/
Create:
SUMMARY.md
one phase file per implementation phase
Add
research/
only if needed.
Step 3: Define Strategy and Phases
Design a phased strategy that is safe and verifiable.
Each phase should have:
A clear objective
Ordered tasks
Verification commands
Exit criteria
Granularity rule:
Tasks should be small, concrete, and typically 2-10 minutes each.
Step 4: Research (Only if Needed)
Research is optional and should be proportional to uncertainty.
Preferred order:
Existing project docs and code
Existing skills and local references
External references (only if available in the current environment)
If external research capability is unavailable, proceed with local evidence and explicitly list assumptions and open questions.
Document findings in:
docs/plans/YYMMDD-HHmm-/research/.md
Step 5: Write Plan Content
SUMMARY.md
format
Implementation Plan:
</p>
<blockquote>
<p>Created: YYYY-MM-DD HH:mm:ss</p>
<p>Status: Draft</p>
</blockquote>
<h2 id="_2"></h2>
<h2 id="objective">Objective</h2>
<p>What is being built/changed and why.</p>
<h2 id="_3"></h2>
<h2 id="scope">Scope</h2>
<h2 id="in-scope">In scope</h2>
<p>Out of scope</p>
<h2 id="_4"></h2>
<h2 id="architecture-approach">Architecture & Approach</h2>
<h2 id="design-decisions-and-rationale">Design decisions and rationale.</h2>
<p>Constraints and compatibility notes.</p>
<h2 id="_5"></h2>
<h2 id="phases">Phases</h2>
<p>[ ]
**
Phase 1: <name>
**
— Goal:
<
goal</p>
<blockquote>
<p>-
[ ]
**
Phase 2: <name>
**
— Goal:
<
goal
</p>
</blockquote>
<h2 id="_6"></h2>
<h2 id="key-changes">Key Changes</h2>
<h2 id="filesmodules-likely-to-change">Files/modules likely to change</h2>
<p>Data/API/schema impacts</p>
<h2 id="_7"></h2>
<h2 id="verification-strategy">Verification Strategy</h2>
<h2 id="linttypechecktestsbuild-commands">Lint/typecheck/tests/build commands</h2>
<p>Manual checks if needed</p>
<h2 id="_8"></h2>
<h2 id="dependencies">Dependencies</h2>
<p>New packages/tools (if any) with reason</p>
<h2 id="_9"></h2>
<h2 id="risks-mitigations">Risks & Mitigations</h2>
<p>Risk → mitigation</p>
<h2 id="_10"></h2>
<h2 id="open-questions">Open Questions</h2>
<p>Items requiring user confirmation
phase-XX-<name>.md
format</p>
<h1 id="_11"></h1>
<p>Phase XX: <Name></p>
<h2 id="_12"></h2>
<h2 id="objective_1">Objective</h2>
<p>Specific result for this phase.</p>
<h2 id="_13"></h2>
<h2 id="preconditions">Preconditions</h2>
<p>What must already be true.</p>
<h2 id="_14"></h2>
<p>Tasks
1.
Context: files/components to inspect or modify
2.
Implement: exact change steps
3.
Verify: commands/checks to run
4.
Confirm: expected outcome</p>
<h2 id="_15"></h2>
<h2 id="verification">Verification</h2>
<h2 id="commands">Commands:</h2>
<p><
command
1</p>
<blockquote>
<p>-
<
command
2</p>
<p>-
Expected results:
-
<
result
</p>
</blockquote>
<h2 id="_16"></h2>
<h2 id="exit-criteria">Exit Criteria</h2>
<dl>
<dt>Clear checklist that determines completion.</dt>
<dt>Step 6: Review and Refine</dt>
<dt>Before presenting the plan, verify:</dt>
<dt>Paths are exact and consistent</dt>
<dt>Phase order is logical</dt>
<dt>Tasks are actionable (no vague steps)</dt>
<dt>Verification is defined for each phase</dt>
<dt>Risks/assumptions are explicit</dt>
<dt>Plan is executable without hidden context</dt>
<dt>Then present for user review.</dt>
<dt>If multiple viable approaches exist, present options and ask for one of:</dt>
<dt>Validate</dt>
<dd>
<dl>
<dt>refine via additional clarifying questions</dt>
<dt>Confirm</dt>
<dd>approve current plan for execution
Iterate until confirmed.
Step 7: Handoff
When approved, end with:
Plan
<relative_path_to_plan>/SUMMARY.md
is ready.
Use
/clear
and then
/execute-plan <relative_path_to_plan>/SUMMARY.md
to execute it.
Rules
Never automatically implement or execute the code change in the same session, or ask user for execution right now, always finished when completed planning and ready for user review.
Prefer explicit file paths and concrete commands
Align with project standards and existing architecture
Ask clarifying questions when uncertainty affects execution safety
Keep plans self-contained and deterministic</dd>
</dl>
</dd>
</dl>
</article>
<a href="/" class="back-link">← <span data-i18n="detail.backToLeaderboard">返回排行榜</span></a>
</div>
<aside class="sidebar">
<section class="related-skills" id="relatedSkillsSection">
<h2 class="related-title" data-i18n="detail.relatedSkills">相关 Skills</h2>
<div class="related-list" id="relatedSkillsList">
<div class="skeleton-card"></div>
<div class="skeleton-card"></div>
<div class="skeleton-card"></div>
</div>
</section>
</aside>
</div>
</div>
<script src="https://unpkg.com/i18next@23.11.5/i18next.min.js" defer></script>
<script src="https://unpkg.com/i18next-browser-languagedetector@7.2.1/i18nextBrowserLanguageDetector.min.js" defer></script>
<script defer>
// Language resources - same pattern as index page
const resources = {
'zh-CN': null,
'en': null,
'ja': null,
'ko': null,
'zh-TW': null,
'es': null,
'fr': null
};
// Load language files (only current + fallback for performance)
async function loadLanguageResources() {
const savedLang = localStorage.getItem('i18nextLng') || 'en';
const langsToLoad = new Set([savedLang, 'en']); // current + fallback
await Promise.all([...langsToLoad].map(async (lang) => {
try {
const response = await fetch(`/locales/${lang}.json`);
if (response.ok) {
resources[lang] = { translation: await response.json() };
}
} catch (error) {
console.warn(`Failed to load ${lang} language file:`, error);
}
}));
}
// Load a single language on demand (for language switching)
async function loadLanguage(lang) {
if (resources[lang]) return;
try {
const response = await fetch(`/locales/${lang}.json`);
if (response.ok) {
resources[lang] = { translation: await response.json() };
i18next.addResourceBundle(lang, 'translation', resources[lang].translation);
}
} catch (error) {
console.warn(`Failed to load ${lang} language file:`, error);
}
}
// Initialize i18next
async function initI18n() {
try {
await loadLanguageResources();
// Filter out null values from resources
const validResources = {};
for (const [lang, data] of Object.entries(resources)) {
if (data !== null) {
validResources[lang] = data;
}
}
console.log('Loaded languages:', Object.keys(validResources));
console.log('zh-CN resource:', validResources['zh-CN']);
console.log('detail.home in resource:', validResources['zh-CN']?.translation?.detail?.home);
// 检查是否有保存的语言偏好
const savedLang = localStorage.getItem('i18nextLng');
// 如果没有保存的语言偏好，默认使用英文
const defaultLang = savedLang && ['zh-CN', 'en', 'ja', 'ko', 'zh-TW', 'es', 'fr'].includes(savedLang)
? savedLang
: 'en';
await i18next
.use(i18nextBrowserLanguageDetector)
.init({
lng: defaultLang, // 强制设置初始语言
fallbackLng: 'en',
supportedLngs: ['zh-CN', 'en', 'ja', 'ko', 'zh-TW', 'es', 'fr'],
resources: validResources,
detection: {
order: ['localStorage'], // 只使用 localStorage，不检测浏览器语言
caches: ['localStorage'],
lookupLocalStorage: 'i18nextLng'
},
interpolation: {
escapeValue: false
}
});
console.log('i18next initialized, language:', i18next.language);
console.log('Test translation:', i18next.t('detail.home'));
// Set initial language in selector
const langSwitcher = document.getElementById('langSwitcher');
langSwitcher.value = i18next.language;
// Update page language
updatePageLanguage();
// Language switch event
langSwitcher.addEventListener('change', async (e) => {
await loadLanguage(e.target.value); // load on demand
i18next.changeLanguage(e.target.value).then(() => {
updatePageLanguage();
localStorage.setItem('i18nextLng', e.target.value);
});
});
} catch (error) {
console.error('i18next init failed:', error);
}
}
// Translation helper
function t(key, options = {}) {
return i18next.t(key, options);
}
// Update all translatable elements
function updatePageLanguage() {
// Update HTML lang attribute
document.documentElement.lang = i18next.language;
// Update elements with data-i18n attribute
document.querySelectorAll('[data-i18n]').forEach(el => {
const key = el.getAttribute('data-i18n');
el.textContent = t(key);
});
}
// Copy command function
function copyCommand() {
const command = document.getElementById('installCommand').textContent;
const btn = document.getElementById('copyBtn');
navigator.clipboard.writeText(command).then(() => {
btn.textContent = t('copied');
btn.classList.add('copied');
setTimeout(() => {
btn.textContent = t('copy');
btn.classList.remove('copied');
}, 2000);
}).catch(() => {
// Fallback for non-HTTPS
const textArea = document.createElement('textarea');
textArea.value = command;
textArea.style.position = 'fixed';
textArea.style.left = '-9999px';
document.body.appendChild(textArea);
textArea.select();
document.execCommand('copy');
document.body.removeChild(textArea);
btn.textContent = t('copied');
btn.classList.add('copied');
setTimeout(() => {
btn.textContent = t('copy');
btn.classList.remove('copied');
}, 2000);
});
}
// Initialize
document.getElementById('copyBtn').addEventListener('click', copyCommand);
initI18n();
// 异步加载相关 Skills
async function loadRelatedSkills() {
const owner = 'buiducnhat';
const skillName = 'write-plan';
const currentLang = 'fr';
const listContainer = document.getElementById('relatedSkillsList');
const section = document.getElementById('relatedSkillsSection');
try {
const response = await fetch(`/api/related-skills/${encodeURIComponent(owner)}/${encodeURIComponent(skillName)}?limit=6`);
if (!response.ok) {
throw new Error('Failed to load');
}
const data = await response.json();
const relatedSkills = data.related_skills || [];
if (relatedSkills.length === 0) {
// 没有相关推荐时隐藏整个区域
section.style.display = 'none';
return;
}
// 渲染相关 Skills
listContainer.innerHTML = relatedSkills.map(skill => {
const desc = skill.description || '';
const truncatedDesc = desc.length > 60 ? desc.substring(0, 60) + '...' : desc;
return `
<a href="${currentLang === 'en' ? '' : '/' + currentLang}/skill/${skill.owner}/${skill.repo}/${skill.skill_name}" class="related-card">
<div class="related-name">${escapeHtml(skill.skill_name)}</div>
<div class="related-meta">
<span class="related-owner">${escapeHtml(skill.owner)}</span>
<span class="related-installs">${skill.installs}</span>
</div>
<div class="related-desc">${escapeHtml(truncatedDesc)}</div>
</a>
`;
}).join('');
} catch (error) {
console.error('Failed to load related skills:', error);
// 加载失败时显示提示或隐藏
listContainer.innerHTML = '<div class="related-empty">暂无相关推荐</div>';
}
}
// HTML 转义
function escapeHtml(text) {
const div = document.createElement('div');
div.textContent = text;
return div.innerHTML;
}
// 页面加载完成后异步加载相关 Skills
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', loadRelatedSkills);
} else {
loadRelatedSkills();
}
</script>
</body>
</html>