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 = `
$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)