Skill: athola/nm-scribe-doc-generator (version 1.0.2)

--- name: doc-generator description: Generate or remediate documentation with human-quality writing and style version: 1.9.5 triggers: - documentation - writing - generation - remediation - polish metadata: {"openclaw": {"homepage": "https://github.com/athola/claude-night-market/tree/master/plugins/scribe", "emoji": "\ud83e\udd9e", "requires": {"config": ["night-market.scribe:shared", "night-market.scribe:slop-detector"]}}} source: claude-night-market source_plugin: scribe --- > **Night Market Skill** — ported from [claude-night-market/scribe](https://github.com/athola/claude-night-market/tree/master/plugins/scribe). For the full experience with agents, hooks, and commands, install the Claude Code plugin. # Documentation Generator Documentation must be grounded in specific claims rather than abstract adjectives. We avoid filler phrases like "In today's fast-paced world" and focus on delivering useful information directly. Each claim should be supported by evidence, such as specific version numbers or request rates, rather than vague descriptors like "comprehensive." ## Core Writing Principles We prioritize authorial perspective and active voice to maintain a consistent team tone. This involves explaining the reasoning behind technical choices, such as selecting one database over another, rather than providing neutral boilerplate. Bullets should be used sparingly for actionable summaries; multi-line bullet waterfalls should be converted to short paragraphs to preserve nuance. ### Vocabulary and Style Avoid business jargon and linguistic tics like mirrored sentence structures or excessive em dashes. We use the imperative mood for docstrings (e.g., "Validate input") and strictly avoid humanizing non-living constructs like code. | Instead of | Use | |------------|-----| | fallback | default, secondary | | leverage | use | | utilize | use | | facilitate | help, enable | | comprehensive | thorough, complete | ### 9. Limit Humanizing Constructs "Lives under," "speaks to," and similar phrases only make sense for living things. ### 10. Imperative Mood for Docstrings "Validate" not "Validates" (per PEP 257, pydocstyle, ruff). ## Required TodoWrite Items 1. `doc-generator:scope-defined` - Target files and type identified 2. `doc-generator:style-loaded` - Style profile applied (if available) 3. `doc-generator:content-drafted` - Initial content created 4. `doc-generator:slop-scanned` - AI markers checked 5. `doc-generator:quality-verified` - Principles checklist passed 6. `doc-generator:user-approved` - Final approval received ## Mode: Generation For new documentation: ### Step 1: Define Scope ```markdown ## Generation Request **Type**: [README/Guide/API docs/Tutorial] **Audience**: [developers/users/admins] **Length target**: [~X words or sections] **Style profile**: [profile name or "default"] ``` ### Step 2: Load Style (if available) If a style profile exists: ```bash cat .scribe/style-profile.yaml ``` Apply voice, vocabulary, and structural guidelines. ### Step 3: Draft Content Follow the 10 core principles above. For each section: 1. Start with the essential information 2. Add context only if it adds value 3. Use specific examples 4. Prefer prose over bullets 5. End when information is complete (no summary padding) ### Step 4: Run Slop Detector ``` Skill(scribe:slop-detector) ``` Fix any findings before proceeding. ### Step 5: Quality Gate Verify against checklist: - [ ] No tier-1 slop words - [ ] Em dash count < 3 per 1000 words - [ ] Bullet ratio < 40% - [ ] All claims grounded with specifics - [ ] No formulaic openers or closers - [ ] Authorial perspective present - [ ] No emojis (unless explicitly requested) ## Mode: Remediation For cleaning up existing content: Load: `@modules/remediation-workflow.md` ### Step 1: Analyze Current State ```bash # Get slop score Skill(scribe:slop-detector) --target file.md ``` ### Step 2: Section-by-Section Approach For large files (>200 lines), edit incrementally: ```markdown ## Section: [Name] (Lines X-Y) **Current slop score**: X.X **Issues found**: [list] **Proposed changes**: 1. [Change 1] 2. [Change 2] **Before**: > [current text] **After**: > [proposed text] Proceed? [Y/n/edit] ``` ### Step 3: Preserve Intent Never change WHAT is said, only HOW. If meaning is unclear, ask. ### Step 4: Re-verify After edits, re-run slop-detector to confirm improvement. ## Docstring-Specific Rules When editing code comments: 1. **ONLY modify docstring/comment text** 2. **Never change surrounding code** 3. **Use imperative mood** ("Validate input" not "Validates input") 4. **Brief is better** - remove filler 5. **Keep Args/Returns structure** if present ## Module Reference - See `modules/generation-guidelines.md` for content creation patterns - See `modules/quality-gates.md` for validation criteria ## Integration with Other Skills | Skill | When to Use | |-------|-------------| | slop-detector | After drafting, before approval | | style-learner | Before generation to load profile | | sanctum:doc-updates | For broader doc maintenance | ## Exit Criteria - Content created or remediated - Slop score < 1.5 (clean rating) - Quality gate checklist passed - User approval received - No emojis present (unless specified)

path: modules/generation-guidelines.md
content: ---
module: generation-guidelines
category: writing-quality
dependencies: []
estimated_tokens: 400
---

# Documentation Generation Guidelines

Detailed guidance for creating human-quality documentation.

## Opening Patterns

### What to Avoid

```markdown
BAD: "In today's fast-paced development environment, documentation plays a crucial role..."
BAD: "Welcome to the comprehensive guide to..."
BAD: "This document aims to provide an in-depth overview of..."
```

### What to Use

```markdown
GOOD: "scribe detects AI-generated content and helps you fix it."
GOOD: "Install with: npm install scribe"
GOOD: "This guide covers installation, configuration, and common workflows."
```

Start with what it IS or what it DOES. Skip the preamble.

## Section Structure

### Length Targets

| Section Type | Target Length |
|--------------|---------------|
| Overview | 50-100 words |
| Feature description | 30-60 words |
| Step in guide | 20-50 words |
| API endpoint | 40-80 words |

### Paragraph Guidance

Paragraphs should contain 2-4 sentences on a single topic. If a paragraph exceeds 5 sentences, split it.

One paragraph = one idea.

## Line Wrapping

Wrap prose text at 80 characters per line using hybrid
wrapping. This makes git diffs readable and mobile-friendly.

### Rules (in priority order)

1. Keep sentences on one line if they fit within 80 chars
2. Break long sentences at clause boundaries (after `, ; :`)
3. Break before conjunctions (`and`, `but`, `or`)
4. Break at word boundaries as a last resort

### Exempt from wrapping

Tables, code blocks, headings, frontmatter, HTML blocks,
link definitions, and image references stay on one line.

### Example

```markdown
BEFORE:
The system validates all input against the schema and rejects
malformed requests with a 400 status code, logging the
validation failure for debugging.

AFTER:
The system validates all input against the schema
and rejects malformed requests with a 400 status code,
logging the validation failure for debugging.
```

### Additional formatting rules

- Blank line before and after every heading
- ATX headings only (`#` style, never setext underlines)
- Blank line before every list
- Use reference-style links when inline links push past
  80 chars

Full specification: `Skill(leyline:markdown-formatting)`

## Concrete Examples

Every feature claim needs a concrete example:

```markdown
BAD: "The system provides flexible configuration options."

GOOD: "Configure via `scribe.yaml` or environment variables.
Set `SCRIBE_STRICT=1` to treat warnings as errors."
```

## Trade-off Discussions

Include reasoning, not just conclusions:

```markdown
BAD: "We recommend Redis for caching."

GOOD: "We chose Redis over Memcached for its sorted sets,
which power the leaderboard. Memcached would use less memory
but require additional application logic."
```

## Ending Patterns

### What to Avoid

```markdown
BAD: "In conclusion, we have covered the essential aspects of..."
BAD: "We hope this guide has been helpful in your journey..."
BAD: "Happy coding!"
```

### What to Use

End with the last useful piece of information. No summary paragraph unless the document exceeds 2000 words.

```markdown
GOOD: "For issues, open a ticket at github.com/org/repo/issues."
GOOD: "Next: Advanced Configuration"
GOOD: [Just end. No closing needed.]
```

## Voice Consistency

Maintain consistent perspective throughout:

| Style | Example |
|-------|---------|
| Direct | "Run `npm install`" |
| Team | "We recommend..." |
| Instructional | "You can configure..." |

Don't mix: "One should note that you can..."

## Handling Uncertainty

When information is incomplete:

```markdown
GOOD: "Exact performance varies by hardware. Our tests showed 50-200ms on M1 Mac."
GOOD: "This feature is experimental. API may change."
GOOD: "We haven't tested on Windows. Linux and macOS confirmed working."
```

Acknowledge limits rather than overgeneralizing.


path: modules/quality-gates.md
content: ---
module: quality-gates
category: writing-quality
dependencies: [TodoWrite]
estimated_tokens: 300
---

# Documentation Quality Gates

Checklists and thresholds for documentation quality validation.

## Pre-Commit Checklist

Before finalizing any documentation:

### Content Quality
- [ ] No tier-1 slop words present
- [ ] No vapid openers or closers
- [ ] All claims grounded with specifics
- [ ] Trade-offs explained, not just conclusions
- [ ] Authorial perspective present ("we chose", "our tests showed")

### Structure Quality
- [ ] Em dash count < 3 per 1000 words
- [ ] Bullet ratio < 40% (unless reference material)
- [ ] Sentence length varies (SD > 5 words)
- [ ] Paragraphs 2-5 sentences each
- [ ] No five-paragraph essay structure

### Style Quality
- [ ] Consistent voice throughout
- [ ] Appropriate formality for audience
- [ ] Contractions used if informal tone
- [ ] No emojis (unless explicitly requested)

### Technical Quality
- [ ] File paths verified to exist
- [ ] Commands tested and working
- [ ] Version numbers accurate
- [ ] Links not broken

## Metric Thresholds

| Metric | Pass | Warning | Fail |
|--------|------|---------|------|
| Slop score | < 1.0 | 1.0-2.5 | > 2.5 |
| Tier 1 words | 0 | 1-2 | 3+ |
| Em dashes | < 3/1000 | 3-5/1000 | > 5/1000 |
| Bullet ratio | < 30% | 30-50% | > 50% |
| Sentence SD | > 8 | 5-8 | < 5 |

## TodoWrite Integration

Track quality gate status:

```
doc-generator:quality-content - PASS/FAIL
doc-generator:quality-structure - PASS/FAIL
doc-generator:quality-style - PASS/FAIL
doc-generator:quality-technical - PASS/FAIL
```

## Remediation Required

If any gate fails:

1. Identify specific failures
2. Propose fixes
3. Apply fixes
4. Re-run gates
5. Repeat until pass

## Exceptions

Document exceptions when gates are intentionally skipped:

```markdown
## Quality Gate Exception

**Document**: API-reference.md
**Gate**: bullet-ratio (58%)
**Reason**: Reference documentation requires list format
**Approved by**: [user]
**Date**: [date]
```

## Integration with CI

For automated checking:

```yaml
# .github/workflows/docs-quality.yaml
- name: Check documentation quality
  run: |
    scribe scan docs/
    if [ $? -ne 0 ]; then
      echo "Documentation quality check failed"
      exit 1
    fi
```


path: modules/remediation-workflow.md
content: ---
module: remediation-workflow
category: writing-quality
dependencies: [Edit, Read]
estimated_tokens: 400
---

# Documentation Remediation Workflow

Step-by-step process for cleaning up AI-generated content.

## Phase 1: Assessment

Run slop-detector and categorize findings:

```markdown
## Remediation Assessment: [filename]

**Slop Score**: X.X
**Word Count**: N

### Critical (fix immediately)
- [ ] Vapid opener at line 1
- [ ] "cannot be overstated" at line 45

### High Priority (fix in this pass)
- [ ] 8 tier-1 slop words
- [ ] Em dash density 7/1000

### Medium Priority (fix if time)
- [ ] Bullet ratio 55%
- [ ] Sentence uniformity

### Low Priority (defer)
- [ ] Minor vocabulary substitutions
```

## Phase 2: User Approval for Major Changes

If remediation requires:
- Deleting entire sections
- Restructuring document flow
- Changing technical content

Always ask:

```markdown
## Major Change Required

The opening section (lines 1-25) is primarily filler with no
technical content. Options:

1. **Delete entirely** - Start at line 26 with actual information
2. **Condense to 2 sentences** - Keep intro but remove fluff
3. **Rewrite** - New opening based on document purpose

Which approach? [1/2/3]
```

## Phase 3: Section-by-Section Editing

For documents over 200 lines, process in sections:

```markdown
## Section 1: Introduction (Lines 1-45)

### Current State
> In today's rapidly evolving technological landscape,
> comprehensive documentation plays a pivotal role in
> ensuring seamless developer experiences...

### Issues
- Vapid opener
- "comprehensive", "pivotal", "seamless" (tier 1/2 words)
- No concrete information in 45 words

### Proposed Revision
> scribe checks documentation for AI-generated patterns
> and provides rewriting guidance. This guide covers
> installation, configuration, and usage.

### Changes
- Removed opener cliche
- Replaced with direct statement
- Cut word count from 45 to 22

Proceed? [Y/n/edit]
```

## Phase 4: Vocabulary Sweep

After structural fixes, sweep for remaining vocabulary:

```bash
# Quick vocabulary check
grep -nE '\b(delve|embark|leverage|utilize|comprehensive)\b' file.md
```

Apply substitutions from shared module:

| Line | Current | Replacement |
|------|---------|-------------|
| 23 | leverage | use |
| 45 | utilize | use |
| 67 | comprehensive | thorough |

## Phase 5: Structural Polish

Final pass for structural issues:

1. **Em dashes**: Replace excessive uses with commas/periods
2. **Lists**: Convert bullet waterfalls to prose
3. **Sentence variation**: Add short/long variety
4. **Contractions**: Add if tone is informal

## Phase 6: Verification

Re-run slop-detector:

```markdown
## Remediation Results

| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Slop score | 4.8 | 1.2 | -75% |
| Tier 1 words | 12 | 0 | -100% |
| Em dash density | 7/1000 | 2/1000 | -71% |
| Bullet ratio | 55% | 30% | -45% |

Status: CLEAN
```

## Docstring Mode

For code files, special handling:

1. Extract docstrings only (don't modify code)
2. Apply vocabulary substitutions
3. Convert to imperative mood
4. Verify with slop-detector
5. Re-insert docstrings

```python
# ONLY these parts change:
def function():
    """
    BEFORE: "This function leverages advanced algorithms to
    comprehensively process the input data."

    AFTER: "Process input data and return result."
    """
    # Code remains EXACTLY as-is
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)