diff --git a/plugins/artifact/skills/artifact/SKILL.md b/plugins/artifact/skills/artifact/SKILL.md index fc7cf43..8318953 100644 --- a/plugins/artifact/skills/artifact/SKILL.md +++ b/plugins/artifact/skills/artifact/SKILL.md @@ -18,7 +18,7 @@ When the user asks for an interactive artifact, playground, explorer, or visual - `templates/design-playground.md` — Visual design decisions (components, layouts, spacing, color, typography) - `templates/data-explorer.md` — Data and query building (SQL, APIs, pipelines, regex) - `templates/concept-map.md` — Learning and exploration (concept maps, knowledge gaps, scope mapping) - - `templates/writing-tool.md` — Writing and content (tone, document structure, audience) + - `templates/document-critique.md` — Document review (suggestions with approve/reject/comment workflow) - `templates/diff-review.md` — Code review (git diffs, commits, PRs with line-by-line commenting) - `templates/code-map.md` — Codebase architecture (component relationships, data flow, layer diagrams) 3. **Follow the template** to build the artifact. If the topic doesn't fit any template cleanly, use the one closest and adapt. diff --git a/plugins/artifact/skills/artifact/templates/document-critique.md b/plugins/artifact/skills/artifact/templates/document-critique.md new file mode 100644 index 0000000..37eea72 --- /dev/null +++ b/plugins/artifact/skills/artifact/templates/document-critique.md @@ -0,0 +1,171 @@ +# Document Critique Template + +Use this template when the artifact helps review and critique documents: SKILL.md files, READMEs, specs, proposals, or any text that needs structured feedback with approve/reject/comment workflow. + +## Layout + +``` ++---------------------------+--------------------+ +| | | +| Document content | Suggestions panel | +| with line numbers | (filterable list) | +| and suggestion | • Approve | +| highlighting | • Reject | +| | • Comment | +| | | ++---------------------------+--------------------+ +| Prompt output (approved + commented items) | +| [ Copy Prompt ] | ++------------------------------------------------+ +``` + +## Key components + +### Document panel (left) +- Display full document with line numbers +- Highlight lines with suggestions using a colored left border +- Color-code by status: pending (amber), approved (green), rejected (red with opacity) +- Click a suggestion card to scroll to the relevant line + +### Suggestions panel (right) +- Filter tabs: All / Pending / Approved / Rejected +- Stats in header showing counts for each status +- Each suggestion card shows: + - Line reference (e.g., "Line 3" or "Lines 17-24") + - The suggestion text + - Action buttons: Approve / Reject / Comment (or Reset if already decided) + - Optional textarea for user comments + +### Prompt output (bottom) +- Generates a prompt only from approved suggestions and user comments +- Groups by: Approved Improvements, Additional Feedback, Rejected (for context) +- Copy button with "Copied!" feedback + +## State structure + +```javascript +const suggestions = [ + { + id: 1, + lineRef: "Line 3", + targetText: "description: Creates interactive...", + suggestion: "The description is too long. Consider shortening.", + category: "clarity", // clarity, completeness, performance, accessibility, ux + status: "pending", // pending, approved, rejected + userComment: "" + }, + // ... more suggestions +]; + +let state = { + suggestions: [...], + activeFilter: "all", + activeSuggestionId: null +}; +``` + +## Suggestion matching to lines + +Match suggestions to document lines by parsing the lineRef: + +```javascript +const suggestion = state.suggestions.find(s => { + const match = s.lineRef.match(/Line[s]?\s*(\d+)/); + if (match) { + const targetLine = parseInt(match[1]); + return Math.abs(targetLine - lineNum) <= 2; // fuzzy match nearby lines + } + return false; +}); +``` + +## Document rendering + +Handle markdown-style formatting inline: + +```javascript +// Skip ``` lines, wrap content in code-block-wrapper +if (line.startsWith('```')) { + inCodeBlock = !inCodeBlock; + // Open or close wrapper div +} + +// Headers +if (line.startsWith('# ')) renderedLine = `

...

`; +if (line.startsWith('## ')) renderedLine = `

...

`; + +// Inline formatting (outside code blocks) +renderedLine = renderedLine.replace(/`([^`]+)`/g, '$1'); +renderedLine = renderedLine.replace(/\*\*([^*]+)\*\*/g, '$1'); +``` + +## Prompt output generation + +Only include actionable items: + +```javascript +function updatePrompt() { + const approved = state.suggestions.filter(s => s.status === 'approved'); + const withComments = state.suggestions.filter(s => s.userComment?.trim()); + + if (approved.length === 0 && withComments.length === 0) { + // Show placeholder + return; + } + + let prompt = 'Please update [DOCUMENT] with the following changes:\n\n'; + + if (approved.length > 0) { + prompt += '## Approved Improvements\n\n'; + for (const s of approved) { + prompt += `**${s.lineRef}:** ${s.suggestion}`; + if (s.userComment?.trim()) { + prompt += `\n → User note: ${s.userComment.trim()}`; + } + prompt += '\n\n'; + } + } + + // Additional feedback from non-approved items with comments + // Rejected items listed for context only +} +``` + +## Styling highlights + +```css +.doc-line.has-suggestion { + border-left: 3px solid #bf8700; /* amber for pending */ + background: rgba(191, 135, 0, 0.08); +} + +.doc-line.approved { + border-left-color: #1a7f37; /* green */ + background: rgba(26, 127, 55, 0.08); +} + +.doc-line.rejected { + border-left-color: #cf222e; /* red */ + background: rgba(207, 34, 46, 0.08); + opacity: 0.6; +} +``` + +## Pre-populating suggestions + +When building a critique artifact for a specific document: + +1. Read the document content +2. Analyze and generate suggestions with: + - Specific line references + - Clear, actionable suggestion text + - Category tags (clarity, completeness, performance, accessibility, ux) +3. Embed both the document content and suggestions array in the HTML + +## Example use cases + +- SKILL.md review (skill definition quality, completeness, clarity) +- README critique (documentation quality, missing sections, unclear explanations) +- Spec review (requirements clarity, missing edge cases, ambiguity) +- Proposal feedback (structure, argumentation, missing context) +- Code comment review (docstring quality, inline comment usefulness) diff --git a/plugins/artifact/skills/artifact/templates/writing-tool.md b/plugins/artifact/skills/artifact/templates/writing-tool.md deleted file mode 100644 index cc4f71e..0000000 --- a/plugins/artifact/skills/artifact/templates/writing-tool.md +++ /dev/null @@ -1,66 +0,0 @@ -# Writing Tool Template - -Use this template when the artifact helps shape writing: tone calibration, document structure planning, audience profiling, content briefs. - -## Layout - -``` -+-------------------+----------------------+ -| | | -| Controls | Live text preview | -| grouped by: | (sample paragraph | -| • Tone | re-rendered with | -| • Audience | current settings, | -| • Structure | or outline skeleton)| -| • Constraints | | -| +----------------------+ -| | Prompt output | -| | [ Copy Prompt ] | -+-------------------+----------------------+ -``` - -## Control types by decision - -| Decision | Control | Example | -|---|---|---| -| Tone axes | Slider pairs | formal↔casual, concise↔detailed, technical↔accessible | -| Audience expertise | Slider | beginner → expert | -| Audience role | Dropdown or chips | engineer, manager, exec, customer | -| Document sections | Drag-and-drop list | reorder outline items | -| Section depth | Per-item dropdown | brief / detailed / skip | -| Word/length constraints | Slider | target length 500–5000 words | - -## Preview rendering - -For tone tools, show a fixed sample paragraph and re-render it with exaggerated characteristics matching the sliders. This gives the user a feel for what "formal + concise" vs "casual + detailed" actually reads like. - -```javascript -const SAMPLES = { - formalConcise: "The system processes requests asynchronously via a distributed queue.", - formalDetailed: "The system architecture relies on an asynchronous message queue to process incoming requests, ...", - casualConcise: "It fires off requests in the background using a queue.", - casualDetailed: "So basically, when a request comes in, it doesn't block — ...", -}; - -function renderPreview() { - // Pick closest sample based on slider positions - const key = closestSampleKey(state.formality, state.conciseness); - document.getElementById('preview').textContent = SAMPLES[key]; -} -``` - -For structure tools, render the outline as an indented list with section labels and depth tags. - -## Prompt output for writing - -Frame it as a writing direction with audience and style constraints: - -> "Write a technical blog post about [TOPIC]. Target audience: mid-level engineers who know React but haven't used concurrent features. Tone: conversational but precise. Structure: intro (brief), problem statement (detailed), solution walkthrough with code examples (detailed), trade-offs (brief). Around 2000 words." - -## Example topics - -- Tone mixer (formal/casual × concise/detailed × technical/accessible — live sample) -- Document structure planner (outline builder with section types and depth) -- Audience profiler (expertise level, role, prior knowledge → writing prompt prefix) -- Content brief builder (topic + audience + structure + constraints → full writing prompt) -- Email drafting helper (recipient type, urgency, action needed → email prompt)