home / skills / rohunvora / cool-claude-skills / comment-mode

comment-mode skill

Q: How many comments will I get?

The goal is sparse, high-signal comments only. Expect a focused set of highlights rather than exhaustive markup.

safe

This skill provides granular draft feedback via highlighted HTML comments, preserving voice while enabling click-to-reveal insights.

npx playbooks add skill rohunvora/cool-claude-skills --skill comment-mode

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

6.7 KB

---
name: comment-mode
description: Granular feedback on drafts without rewriting. Generates highlighted HTML with click-to-reveal inline comments. Use when user says "comment on this", "leave comments on", "give feedback on", or asks for feedback on a draft. Supports multiple lenses—editor feedback, POV simulation ("as brian would react"), or focused angles ("word choice only", "weak arguments"). A granular alternative to rewrites that lets users review feedback incrementally without losing their voice.
---

# Comment Mode

Generate highlighted HTML with click-to-reveal comments for granular feedback on text. Alternative to rewrites—user keeps their voice, reviews feedback incrementally.

## When to Use

- User says: "comment on this", "leave comments on", "give feedback on"
- User pastes text and asks for feedback/critique
- User wants targeted feedback without a full rewrite

## Clarify Before Commenting

Use AskUserQuestion to clarify scope when the request is ambiguous. Avoid over-commenting (overwhelming) or under-commenting (missing the point).

**Clarify when:**
- No lens specified → ask what angle they want
- Long document → ask if they want full coverage or just key sections
- Unclear audience → ask who the recipient is (affects POV comments)

**Skip clarification when:**
- Lens is explicit ("comment on word choice only")
- Document is short (<500 words)
- Context is obvious from conversation

**Example clarification:**
```
User: "comment on this"
[long doc, no lens specified]

→ Use AskUserQuestion:
  "What should I focus on?"
  Options:
  - "Editor feedback (structure, clarity, word choice)"
  - "Recipient POV (how [person] would react)"
  - "Specific angle (tell me what)"
```

## Lenses

| Lens | Color | Comment style |
|------|-------|---------------|
| Editor | Yellow (#fff3cd) | observations, suggestions: "weak opener", "add proof here" |
| POV (as person) | Blue (#e3f2fd) | reactions from that person's perspective: "i know this already", "legal would freak out" |
| Focused | Yellow | specific angle only: "word choice", "tone", "weak arguments" |

## Comment Style

- Always lowercase
- Short (5-15 words)
- Smart about type: observations when noting, suggestions when alternatives help, reactions when simulating POV
- Only comment where there's something worth saying—sparse beats exhaustive

## Output Rules

**DO:**
- Write to `_private/views/{name}-comments-temp.html`
- Open with `open _private/views/{name}-comments-temp.html`
- Use highlight colors matching the lens
- Keep comments sparse and high-signal

**DO NOT:**
- Comment on everything—only where there's an obvious edit or insight
- Over-explain in comments—keep them punchy
- Mix lenses in one output—pick one and stick to it

## Template

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{title}</title>
  <style>
    * { box-sizing: border-box; }
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      max-width: 700px;
      margin: 0 auto;
      padding: 40px 20px;
      line-height: 1.7;
      color: #1a1a1a;
      background: #fafafa;
    }
    h1, h2, h3 { margin-top: 2em; font-weight: 600; }
    h1 { font-size: 1.4em; }
    h2 { font-size: 1.2em; color: #333; }
    p { margin: 1em 0; }

    .highlight {
      background: {highlight-bg};  /* #fff3cd yellow for editor, #e3f2fd blue for POV */
      padding: 1px 4px;
      border-radius: 3px;
      cursor: pointer;
      border-bottom: 2px solid {highlight-border};  /* #ffc107 for editor, #2196f3 for POV */
      transition: background 0.15s;
    }
    .highlight:hover, .highlight.active {
      background: {highlight-hover};  /* #ffe69c for editor, #bbdefb for POV */
    }

    .comment {
      display: none;
      background: {comment-bg};  /* #1a1a1a for editor, #0052cc for POV */
      color: #fff;
      padding: 8px 12px;
      border-radius: 6px;
      font-size: 0.85em;
      margin: 8px 0;
      line-height: 1.5;
    }
    .comment.show { display: block; }

    .section-break {
      border: none;
      border-top: 1px solid #ddd;
      margin: 2em 0;
    }

    .legend {
      position: fixed;
      bottom: 20px;
      right: 20px;
      background: #fff;
      padding: 12px 16px;
      border-radius: 8px;
      box-shadow: 0 2px 12px rgba(0,0,0,0.1);
      font-size: 0.8em;
      color: #666;
    }
  </style>
</head>
<body>

{content with <span class="highlight" data-comment="comment text">highlighted phrase</span>}

<div class="legend">{count} comments · click highlights to reveal</div>

<script>
document.querySelectorAll('.highlight').forEach(el => {
  const commentText = el.getAttribute('data-comment');
  const commentDiv = document.createElement('div');
  commentDiv.className = 'comment';
  commentDiv.textContent = commentText;
  el.insertAdjacentElement('afterend', commentDiv);

  el.addEventListener('click', () => {
    const wasActive = el.classList.contains('active');
    document.querySelectorAll('.highlight').forEach(h => h.classList.remove('active'));
    document.querySelectorAll('.comment').forEach(c => c.classList.remove('show'));
    if (!wasActive) {
      el.classList.add('active');
      commentDiv.classList.add('show');
    }
  });
});
</script>
</body>
</html>
```

### Color Reference

**Editor lens (yellow):**
```css
.highlight { background: #fff3cd; border-bottom: 2px solid #ffc107; }
.highlight:hover, .highlight.active { background: #ffe69c; }
.comment { background: #1a1a1a; }
```

**POV lens (blue):**
```css
.highlight { background: #e3f2fd; border-bottom: 2px solid #2196f3; }
.highlight:hover, .highlight.active { background: #bbdefb; }
.comment { background: #0052cc; }
```

## Workflow

1. User pastes text + asks for comments
2. **If ambiguous**: Use AskUserQuestion to clarify lens/scope
3. Read text, identify key phrases worth commenting on (sparse, high-signal)
4. Generate HTML with highlights and `data-comment` attributes
5. Write to `_private/views/{name}-comments-temp.html`
6. Run `open _private/views/{name}-comments-temp.html`

## Examples

**Editor lens:**
```
User: "comment on this, focus on word choice"
→ Yellow highlights, suggestions like "vague, try 'specifically'" or "jargon, simplify"
```

**POV lens:**
```
User: "comment on this as brian would react"
→ Blue highlights, reactions like "i already know this" or "legal would push back here"
```

**Focused lens:**
```
User: "leave comments on this, only flag weak arguments"
→ Yellow highlights on weak claims, comments like "needs evidence" or "assumes too much"
```

**Sparse/sharp lens:**
```
User: "comment only where there's an obvious fix"
→ Minimal highlights, only typos, missing words, or clear improvements
```

Overview

This skill provides granular, non-invasive feedback on drafts by generating highlighted HTML with click-to-reveal inline comments. It preserves the author’s voice by pointing out specific issues and suggestions instead of producing full rewrites. Use it when you want targeted critique from different angles or a simulated recipient POV.

How this skill works

When asked to "comment on this" or similar, the skill inspects the pasted text and identifies high-signal spots worth feedback. It applies a single chosen lens (editor, POV, or a focused angle), wraps highlighted phrases in HTML spans, and attaches concise data-comment tooltips you can click to reveal. The output is a compact HTML view with consistent styling and a legend that shows comment count.

When to use it

You ask: "comment on this", "leave comments on", or "give feedback on"
You paste a draft and want targeted critique without a rewrite
You want feedback from a simulated person (e.g., "as Brian would react")
You need a narrow lens (word choice only, weak arguments)
You want sparse, high-signal notes instead of exhaustive markup

Best practices

Clarify the lens when the request is ambiguous (editor, POV, or specific angle)
Pick one lens per run—do not mix lenses in a single output
Keep comments short (5–15 words) and all lowercase for consistency
Be sparse: only comment where there is clear value or an obvious fix
For long docs, ask whether to review the whole text or only key sections

Example use cases

Editor lens to flag clunky phrasing, unclear claims, or weak openers
POV lens to simulate how a stakeholder or reviewer might react to specific lines
Focused lens to surface only tone issues, word choice, or unsupported arguments
Quick pass to catch typos and obvious fixes without altering voice
Iterative review: request sparse comments, revise, then request another focused pass

FAQ

What lenses are available?

Editor (structure/clarity/word choice), POV (simulate a person’s reactions), and Focused (single-angle checks like word choice or weak arguments).

Should I always clarify scope first?

Clarify when the request is vague, the document is long, or the audience is unclear. Skip clarification for short texts (<500 words) or when the lens is explicit.

How many comments will I get?

The goal is sparse, high-signal comments only. Expect a focused set of highlights rather than exhaustive markup.