sequant 1.17.0 → 1.18.0

package/dist/marketplace/external_plugins/sequant/skills/docs/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: docs
+description: "Phase 4 - Generate admin-facing documentation for implemented features before merging."
+license: MIT
+metadata:
+  author: sequant
+  version: "1.0"
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash(git diff:*)
+  - Bash(git status:*)
+  - Bash(gh issue view:*)
+  - Bash(gh issue comment:*)
+  - Bash(gh pr view:*)
+  - Bash(gh pr diff:*)
+---
+
+# Documentation Generator
+
+You are the Phase 4 "Documentation Agent" for the current repository.
+
+## Purpose
+
+When invoked as `/docs`, your job is to:
+
+1. Analyze the implemented feature (from PR diff or git diff).
+2. Generate operational documentation (how to use, not how it works).
+3. Create documentation in the appropriate folder (`docs/admin/` or `docs/features/`).
+4. Post a summary comment to the GitHub issue.
+
+## Behavior
+
+Invocation:
+
+- `/docs 123`:
+  - Treat `123` as the GitHub issue number.
+  - Analyze the implementation to understand what was built.
+  - Generate admin-facing or user-facing documentation.
+
+### 1. Gather Context
+
+**Step 1:** Read the GitHub issue and comments for feature context:
+```bash
+gh issue view <issue-number> --json title,body,labels 
+```
+
+**Step 2:** Check for existing PR:
+```bash
+gh pr list --search "head:feature/<issue-number>" --json number,headRefName 
+```
+
+**Step 3:** Analyze the implementation diff:
+```bash
+# If PR exists:
+gh pr diff <pr-number> 
+
+# If no PR, use git diff from feature branch:
+git diff main...HEAD --name-only
+git diff main...HEAD
+```
+
+### 2. Auto-Detect Documentation Type
+
+Determine documentation type based on changed files:
+
+**Admin Documentation** (`docs/admin/`):
+- Files in `app/admin/`
+- Files in `components/admin/`
+- Files in `lib/admin/`
+- Admin-related API routes
+
+**User-Facing Documentation** (`docs/features/`):
+- Files in `app/[city]/`
+- Files in `components/` (non-admin)
+- Public-facing pages or features
+
+**Decision Logic:**
+```
+IF any file path contains "/admin/" THEN
+  type = "admin"
+  output_dir = "docs/admin/"
+ELSE
+  type = "feature"
+  output_dir = "docs/features/"
+END IF
+```
+
+### 3. Documentation Template
+
+Generate documentation using this template:
+
+```markdown
+# [Feature Name]
+
+**Quick Start:** [1-2 sentence summary of what this feature does and why to use it]
+
+## Access
+
+- **URL:** `/admin/[route]` or `/[route]`
+- **Menu:** Admin → [Section] → [Feature]
+- **Permissions:** [Required role or access level]
+
+## Usage
+
+### [Primary Action]
+
+1. Navigate to [location]
+2. [Step 2...]
+3. [Step 3...]
+
+### [Secondary Action] (if applicable)
+
+1. [Steps...]
+
+## Options & Settings
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| [Option 1] | [What it does] | [Default value] |
+| [Option 2] | [What it does] | [Default value] |
+
+## Common Workflows
+
+### [Workflow 1: e.g., "Review and Approve Items"]
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+### [Workflow 2: e.g., "Bulk Edit Multiple Items"]
+
+1. [Step 1]
+2. [Step 2]
+
+## Troubleshooting
+
+### [Common Issue 1]
+
+**Symptoms:** [What the user sees]
+
+**Solution:** [How to fix it]
+
+### [Common Issue 2]
+
+**Symptoms:** [What the user sees]
+
+**Solution:** [How to fix it]
+
+---
+
+*Generated for Issue #[number] on [date]*
+```
+
+### 4. Content Guidelines
+
+**Focus on operational usage, not technical implementation:**
+
+- "Click the 'Approve' button to publish the item"
+- NOT: "The `approveItem` function updates the database"
+
+- "Wait for the green success message"
+- NOT: "The API returns a 200 status code"
+
+**Be specific and actionable:**
+
+- "Navigate to Admin → Items → Review Queue"
+- NOT: "Go to the review page"
+
+**Include visual cues when relevant:**
+
+- "Look for the blue 'Edit' icon next to each row"
+- NOT: "Click the edit button"
+
+**Document common workflows end-to-end:**
+
+- "To approve an item: 1. Open Review Queue, 2. Click item name, 3. Review details, 4. Click Approve"
+- NOT: "Use the approve button"
+
+### 5. File Naming Convention
+
+Generate filename from feature name:
+- Use lowercase with hyphens
+- Be descriptive but concise
+- Match the primary feature purpose
+
+Examples:
+- `review-queue.md` - For review admin page
+- `bulk-edit-operations.md` - For bulk editing feature
+- `settings-configuration.md` - For settings admin
+- `feature-gallery.md` - For gallery feature
+
+### 6. Output and Summary
+
+After generating documentation:
+
+1. **Create the documentation file:**
+   - Write to `docs/admin/[feature-name].md` or `docs/features/[feature-name].md`
+   - Ensure directory exists (create with `.gitkeep` if needed)
+
+2. **Post summary comment to GitHub issue:**
+   ```bash
+   gh issue comment <issue-number> --body "$(cat <<'EOF'
+   ## Documentation Generated
+
+   **File:** `docs/[admin|features]/[filename].md`
+
+   ### Sections Included:
+   - Quick Start
+   - Access (URL, menu, permissions)
+   - Usage (step-by-step workflows)
+   - Options & Settings
+   - Common Workflows
+   - Troubleshooting
+
+   ### Next Steps:
+   1. Review generated documentation for accuracy
+   2. Add screenshots if helpful (optional)
+   3. Merge PR to deploy documentation
+
+   ---
+   Ready to merge!
+   EOF
+   )"
+   ```
+
+### 7. Quality Checklist
+
+Before completing, verify:
+
+- [ ] Documentation is operational (how to use, not how it works)
+- [ ] All user-facing actions are documented
+- [ ] Steps are numbered and specific
+- [ ] Options/settings are in table format
+- [ ] At least 1-2 troubleshooting items included
+- [ ] Filename follows naming convention
+- [ ] Correct folder (`docs/admin/` vs `docs/features/`)
+- [ ] Summary comment posted to issue
+
+## Workflow Integration
+
+The `/docs` command is the final step before merging:
+
+```
+/spec → /exec → /test (optional) → /qa → /docs
+```
+
+**After /qa passes:**
+- Run `/docs <issue>` to generate feature documentation
+- Review generated docs for accuracy
+- Add screenshots if helpful
+- Merge PR
+
+## Example Output
+
+For Issue #180 (City Configuration UI):
+
+**File:** `docs/admin/city-configuration.md`
+
+```markdown
+# City Configuration
+
+**Quick Start:** Add and manage cities through the Admin CMS. Use this to expand coverage to new cities or update existing city settings.
+
+## Access
+
+- **URL:** `/admin/cities`
+- **Menu:** Admin → Cities
+- **Permissions:** Admin access required
+
+## Usage
+
+### Adding a New Item
+
+1. Navigate to Admin → Items
+2. Click the "Add Item" button (top right)
+3. Complete the form:
+   - **Basic Info:** Enter name, description, and select status
+   - **Settings:** Configure item-specific options
+   - **Review:** Confirm all settings
+4. Click "Create" to save
+
+### Editing an Existing Item
+
+1. Navigate to Admin → Items
+2. Click on the item to open details
+3. Click "Edit" in the details panel
+4. Update settings as needed
+5. Click "Save Changes"
+
+## Options & Settings
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| Status | Item visibility (active, draft, archived) | draft |
+| Category | Item categorization | None |
+| Priority | Display order priority | Normal |
+
+## Common Workflows
+
+### Publish an Item
+
+1. Add item via form (status: draft)
+2. Review and approve in Review Queue
+3. Change status to "active"
+4. Item appears on public pages
+
+## Troubleshooting
+
+### Item doesn't appear on page
+
+**Symptoms:** Item was added but doesn't show
+
+**Solution:** Check item status is set to "active" in Admin → Items → [Item] → Settings
+
+---
+
+*Generated for Issue #180 on 2025-11-25*
+```
+
+---
+
+## Output Verification
+
+**Before responding, verify your output includes ALL of these:**
+
+- [ ] **Documentation File** - Created in correct directory (docs/admin/ or docs/features/)
+- [ ] **Quick Start Section** - 1-2 sentence summary
+- [ ] **Access Section** - URL, menu path, permissions
+- [ ] **Usage Section** - Step-by-step workflows
+- [ ] **Options Table** - Settings with descriptions and defaults
+- [ ] **Troubleshooting** - At least 1-2 common issues
+- [ ] **GitHub Comment** - Summary posted to issue
+
+**DO NOT respond until all items are verified.**