Replace writing-tool template with document-critique template

- Add document-critique.md template for review artifacts with
  approve/reject/comment workflow
- Remove writing-tool.md template
- Update SKILL.md to reference new template
This commit is contained in:
Thariq Shihipar
2026-01-29 01:16:26 -08:00
parent 09e3d78e31
commit 54402a7c90
3 changed files with 172 additions and 67 deletions

View File

@@ -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/design-playground.md` — Visual design decisions (components, layouts, spacing, color, typography)
- `templates/data-explorer.md` — Data and query building (SQL, APIs, pipelines, regex) - `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/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/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) - `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. 3. **Follow the template** to build the artifact. If the topic doesn't fit any template cleanly, use the one closest and adapt.

View File

@@ -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 = `<h1>...</h1>`;
if (line.startsWith('## ')) renderedLine = `<h2>...</h2>`;
// Inline formatting (outside code blocks)
renderedLine = renderedLine.replace(/`([^`]+)`/g, '<code>$1</code>');
renderedLine = renderedLine.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
```
## 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)

View File

@@ -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 5005000 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)