claude-code-workflow 6.3.9 → 6.3.11

package/.claude/skills/software-manual/specs/quality-standards.md

@@ -0,0 +1,253 @@
+# Quality Standards
+
+Quality gates and standards for software manual generation.
+
+## Quality Dimensions
+
+### 1. Completeness (25%)
+
+All required sections present and adequately covered.
+
+| Requirement | Weight | Criteria |
+|-------------|--------|----------|
+| Overview section | 5 | Product intro, features, quick start |
+| UI Guide | 5 | All major screens documented |
+| API Reference | 5 | All public APIs documented |
+| Configuration | 4 | All config options explained |
+| Troubleshooting | 3 | Common issues addressed |
+| Examples | 3 | Multi-level examples provided |
+
+**Scoring**:
+- 100%: All sections present with adequate depth
+- 80%: All sections present, some lacking depth
+- 60%: Missing 1-2 sections
+- 40%: Missing 3+ sections
+- 0%: Critical sections missing (overview, UI guide)
+
+### 2. Consistency (25%)
+
+Terminology, style, and structure uniform across sections.
+
+| Aspect | Check |
+|--------|-------|
+| Terminology | Same term for same concept throughout |
+| Formatting | Consistent heading levels, code block styles |
+| Tone | Consistent formality level |
+| Cross-references | All internal links valid |
+| Screenshot naming | Follow `ss-{feature}-{action}` pattern |
+
+**Scoring**:
+- 100%: Zero inconsistencies
+- 80%: 1-3 minor inconsistencies
+- 60%: 4-6 inconsistencies
+- 40%: 7-10 inconsistencies
+- 0%: Pervasive inconsistencies
+
+### 3. Depth (25%)
+
+Content provides sufficient detail for target audience.
+
+| Level | Criteria |
+|-------|----------|
+| Shallow | Basic descriptions only |
+| Standard | Descriptions + usage examples |
+| Deep | Descriptions + examples + edge cases + best practices |
+
+**Per-Section Depth Check**:
+- [ ] Explains "what" (definition)
+- [ ] Explains "why" (rationale)
+- [ ] Explains "how" (procedure)
+- [ ] Provides examples
+- [ ] Covers edge cases
+- [ ] Includes tips/best practices
+
+**Scoring**:
+- 100%: Deep coverage on all critical sections
+- 80%: Standard coverage on all sections
+- 60%: Shallow coverage on some sections
+- 40%: Missing depth in critical areas
+- 0%: Superficial throughout
+
+### 4. Readability (25%)
+
+Clear, user-friendly writing that's easy to follow.
+
+| Metric | Target |
+|--------|--------|
+| Sentence length | Average < 20 words |
+| Paragraph length | Average < 5 sentences |
+| Heading hierarchy | Proper H1 > H2 > H3 nesting |
+| Code blocks | Language specified |
+| Lists | Used for 3+ items |
+| Screenshots | Placed near relevant text |
+
+**Structural Elements**:
+- [ ] Clear section headers
+- [ ] Numbered steps for procedures
+- [ ] Bullet lists for options/features
+- [ ] Tables for comparisons
+- [ ] Code blocks with syntax highlighting
+- [ ] Screenshots with captions
+
+**Scoring**:
+- 100%: All readability criteria met
+- 80%: Minor structural issues
+- 60%: Some sections hard to follow
+- 40%: Significant readability problems
+- 0%: Unclear, poorly structured
+
+## Overall Quality Score
+
+```
+Overall = (Completeness × 0.25) + (Consistency × 0.25) +
+          (Depth × 0.25) + (Readability × 0.25)
+```
+
+**Quality Gates**:
+
+| Gate | Threshold | Action |
+|------|-----------|--------|
+| Pass | ≥ 80% | Proceed to HTML generation |
+| Review | 60-79% | Address warnings, proceed with caution |
+| Fail | < 60% | Must address errors before continuing |
+
+## Issue Classification
+
+### Errors (Must Fix)
+
+- Missing required sections
+- Invalid cross-references
+- Broken screenshot markers
+- Code blocks without language
+- Incomplete procedures (missing steps)
+
+### Warnings (Should Fix)
+
+- Terminology inconsistencies
+- Sections lacking depth
+- Missing examples
+- Long paragraphs (> 7 sentences)
+- Screenshots missing captions
+
+### Info (Nice to Have)
+
+- Optimization suggestions
+- Additional example opportunities
+- Alternative explanations
+- Enhancement ideas
+
+## Quality Checklist
+
+### Pre-Generation
+
+- [ ] All agents completed successfully
+- [ ] No errors in consolidation report
+- [ ] Overall score ≥ 60%
+
+### Post-Generation
+
+- [ ] HTML renders correctly
+- [ ] Search returns relevant results
+- [ ] All screenshots display
+- [ ] Theme toggle works
+- [ ] Print preview looks good
+
+### Final Review
+
+- [ ] User previewed and approved
+- [ ] File size reasonable (< 10MB)
+- [ ] No console errors in browser
+- [ ] Accessible (keyboard navigation works)
+
+## Automated Checks
+
+```javascript
+function runQualityChecks(workDir) {
+  const results = {
+    completeness: checkCompleteness(workDir),
+    consistency: checkConsistency(workDir),
+    depth: checkDepth(workDir),
+    readability: checkReadability(workDir)
+  };
+
+  results.overall = (
+    results.completeness * 0.25 +
+    results.consistency * 0.25 +
+    results.depth * 0.25 +
+    results.readability * 0.25
+  );
+
+  return results;
+}
+
+function checkCompleteness(workDir) {
+  const requiredSections = [
+    'section-overview.md',
+    'section-ui-guide.md',
+    'section-api-reference.md',
+    'section-configuration.md',
+    'section-troubleshooting.md',
+    'section-examples.md'
+  ];
+
+  const existing = Glob(`${workDir}/sections/section-*.md`);
+  const found = requiredSections.filter(s =>
+    existing.some(e => e.endsWith(s))
+  );
+
+  return (found.length / requiredSections.length) * 100;
+}
+
+function checkConsistency(workDir) {
+  // Check terminology, cross-references, naming conventions
+  const issues = [];
+
+  // ... implementation ...
+
+  return Math.max(0, 100 - issues.length * 10);
+}
+
+function checkDepth(workDir) {
+  // Check content length, examples, edge cases
+  const sections = Glob(`${workDir}/sections/section-*.md`);
+  let totalScore = 0;
+
+  for (const section of sections) {
+    const content = Read(section);
+    let sectionScore = 0;
+
+    if (content.length > 500) sectionScore += 20;
+    if (content.includes('```')) sectionScore += 20;
+    if (content.includes('Example')) sectionScore += 20;
+    if (content.match(/\d+\./g)?.length > 3) sectionScore += 20;
+    if (content.includes('Note:') || content.includes('Tip:')) sectionScore += 20;
+
+    totalScore += sectionScore;
+  }
+
+  return totalScore / sections.length;
+}
+
+function checkReadability(workDir) {
+  // Check structure, formatting, organization
+  const sections = Glob(`${workDir}/sections/section-*.md`);
+  let issues = 0;
+
+  for (const section of sections) {
+    const content = Read(section);
+
+    // Check heading hierarchy
+    if (!content.startsWith('# ')) issues++;
+
+    // Check code block languages
+    const codeBlocks = content.match(/```\w*/g);
+    if (codeBlocks?.some(b => b === '```')) issues++;
+
+    // Check paragraph length
+    const paragraphs = content.split('\n\n');
+    if (paragraphs.some(p => p.split('. ').length > 7)) issues++;
+  }
+
+  return Math.max(0, 100 - issues * 10);
+}
+```

package/.claude/skills/software-manual/specs/writing-style.md

@@ -0,0 +1,298 @@
+# Writing Style Guide
+
+User-friendly writing standards for software manuals.
+
+## Core Principles
+
+### 1. User-Centered
+
+Write for the user, not the developer.
+
+**Do**:
+- "Click the **Save** button to save your changes"
+- "Enter your email address in the login form"
+
+**Don't**:
+- "The onClick handler triggers the save mutation"
+- "POST to /api/auth/login with email in body"
+
+### 2. Action-Oriented
+
+Focus on what users can **do**, not what the system does.
+
+**Do**:
+- "You can export your data as CSV"
+- "To create a new project, click **New Project**"
+
+**Don't**:
+- "The system exports data in CSV format"
+- "A new project is created when the button is clicked"
+
+### 3. Clear and Direct
+
+Use simple, straightforward language.
+
+**Do**:
+- "Select a file to upload"
+- "The maximum file size is 10MB"
+
+**Don't**:
+- "Utilize the file selection interface to designate a file for uploading"
+- "File size constraints limit uploads to 10 megabytes"
+
+## Tone
+
+### Friendly but Professional
+
+- Conversational but not casual
+- Helpful but not condescending
+- Confident but not arrogant
+
+**Examples**:
+
+| Too Casual | Just Right | Too Formal |
+|------------|------------|------------|
+| "Yo, here's how..." | "Here's how to..." | "The following procedure describes..." |
+| "Easy peasy!" | "That's all you need to do." | "The procedure has been completed." |
+| "Don't worry about it" | "You don't need to change this" | "This parameter does not require modification" |
+
+### Second Person
+
+Address the user directly as "you".
+
+**Do**: "You can customize your dashboard..."
+**Don't**: "Users can customize their dashboards..."
+
+## Structure
+
+### Headings
+
+Use clear, descriptive headings that tell users what they'll learn.
+
+**Good Headings**:
+- "Getting Started"
+- "Creating Your First Project"
+- "Configuring Email Notifications"
+- "Troubleshooting Login Issues"
+
+**Weak Headings**:
+- "Overview"
+- "Step 1"
+- "Settings"
+- "FAQ"
+
+### Procedures
+
+Number steps for sequential tasks.
+
+```markdown
+## Creating a New User
+
+1. Navigate to **Settings** > **Users**.
+2. Click the **Add User** button.
+3. Enter the user's email address.
+4. Select a role from the dropdown.
+5. Click **Save**.
+
+The new user will receive an invitation email.
+```
+
+### Features/Options
+
+Use bullet lists for non-sequential items.
+
+```markdown
+## Export Options
+
+You can export your data in several formats:
+
+- **CSV**: Compatible with spreadsheets
+- **JSON**: Best for developers
+- **PDF**: Ideal for sharing reports
+```
+
+### Comparisons
+
+Use tables for comparing options.
+
+```markdown
+## Plan Comparison
+
+| Feature | Free | Pro | Enterprise |
+|---------|------|-----|------------|
+| Projects | 3 | Unlimited | Unlimited |
+| Storage | 1GB | 10GB | 100GB |
+| Support | Community | Email | Dedicated |
+```
+
+## Content Types
+
+### Conceptual (What Is)
+
+Explain what something is and why it matters.
+
+```markdown
+## What is a Workspace?
+
+A workspace is a container for your projects and team members. Each workspace
+has its own settings, billing, and permissions. You might create separate
+workspaces for different clients or departments.
+```
+
+### Procedural (How To)
+
+Step-by-step instructions for completing a task.
+
+```markdown
+## How to Create a Workspace
+
+1. Click your profile icon in the top-right corner.
+2. Select **Create Workspace**.
+3. Enter a name for your workspace.
+4. Choose a plan (you can upgrade later).
+5. Click **Create**.
+
+Your new workspace is ready to use.
+```
+
+### Reference (API/Config)
+
+Detailed specifications and parameters.
+
+```markdown
+## Configuration Options
+
+### `DATABASE_URL`
+
+- **Type**: String (required)
+- **Format**: `postgresql://user:password@host:port/database`
+- **Example**: `postgresql://admin:secret@localhost:5432/myapp`
+
+Database connection string for PostgreSQL.
+```
+
+## Formatting
+
+### Bold
+
+Use for:
+- UI elements: Click **Save**
+- First use of key terms: **Workspaces** contain projects
+- Emphasis: **Never** share your API key
+
+### Italic
+
+Use for:
+- Introducing new terms: A *workspace* is...
+- Placeholders: Replace *your-api-key* with...
+- Emphasis (sparingly): This is *really* important
+
+### Code
+
+Use for:
+- Commands: Run `npm install`
+- File paths: Edit `config/settings.json`
+- Environment variables: Set `DATABASE_URL`
+- API endpoints: POST `/api/users`
+- Code references: The `handleSubmit` function
+
+### Code Blocks
+
+Always specify the language.
+
+```javascript
+// Example: Fetching user data
+const response = await fetch('/api/user');
+const user = await response.json();
+```
+
+### Notes and Warnings
+
+Use for important callouts.
+
+```markdown
+> **Note**: This feature requires a Pro plan.
+
+> **Warning**: Deleting a workspace cannot be undone.
+
+> **Tip**: Use keyboard shortcuts to work faster.
+```
+
+## Screenshots
+
+### When to Include
+
+- First time showing a UI element
+- Complex interfaces
+- Before/after comparisons
+- Error states
+
+### Guidelines
+
+- Capture just the relevant area
+- Use consistent dimensions
+- Highlight important elements
+- Add descriptive captions
+
+```markdown
+<!-- SCREENSHOT: id="ss-dashboard" description="Main dashboard showing project list" -->
+
+*The dashboard displays all your projects with their status.*
+```
+
+## Examples
+
+### Good Section Example
+
+```markdown
+## Inviting Team Members
+
+You can invite colleagues to collaborate on your projects.
+
+### To invite a team member:
+
+1. Open **Settings** > **Team**.
+2. Click **Invite Member**.
+3. Enter their email address.
+4. Select their role:
+   - **Admin**: Full access to all settings
+   - **Editor**: Can edit projects
+   - **Viewer**: Read-only access
+5. Click **Send Invite**.
+
+The person will receive an email with a link to join your workspace.
+
+> **Note**: You can have up to 5 team members on the Free plan.
+
+<!-- SCREENSHOT: id="ss-invite-team" description="Team invitation dialog" -->
+```
+
+## Language Guidelines
+
+### Avoid Jargon
+
+| Technical | User-Friendly |
+|-----------|---------------|
+| Execute | Run |
+| Terminate | Stop, End |
+| Instantiate | Create |
+| Invoke | Call, Use |
+| Parameterize | Set, Configure |
+| Persist | Save |
+
+### Be Specific
+
+| Vague | Specific |
+|-------|----------|
+| "Click the button" | "Click **Save**" |
+| "Enter information" | "Enter your email address" |
+| "An error occurred" | "Your password must be at least 8 characters" |
+| "It takes a moment" | "This typically takes 2-3 seconds" |
+
+### Use Active Voice
+
+| Passive | Active |
+|---------|--------|
+| "The file is uploaded" | "Upload the file" |
+| "Settings are saved" | "Click **Save** to keep your changes" |
+| "Errors are displayed" | "The form shows any errors" |