@mohammadhprp/system-prompt 0.12.0 → 0.12.2

package/framework/skills/glab/references/troubleshooting.md

@@ -0,0 +1,669 @@
+# glab Troubleshooting Guide
+
+Comprehensive troubleshooting guide for common glab CLI issues and errors.
+
+## Installation Issues
+
+### Command Not Found
+
+**Error:**
+```
+command not found: glab
+```
+or
+```
+glab: command not found
+```
+
+**Causes:**
+- glab is not installed
+- glab is not in PATH
+
+**Solutions:**
+1. Verify installation:
+   ```bash
+   which glab
+   ```
+
+2. Install glab if missing (see main README for installation instructions)
+
+3. If installed but not in PATH, add to PATH:
+   ```bash
+   # Find where glab is installed
+   find / -name glab 2>/dev/null
+
+   # Add to PATH in ~/.bashrc or ~/.zshrc
+   export PATH="$PATH:/path/to/glab"
+   ```
+
+4. For Go installation, ensure `$GOPATH/bin` is in PATH:
+   ```bash
+   export PATH="$PATH:$(go env GOPATH)/bin"
+   ```
+
+### Version Conflicts
+
+**Error:**
+```
+glab: incompatible version
+```
+
+**Solution:**
+Update to the latest version:
+```bash
+# macOS
+brew upgrade glab
+
+# Linux (depends on package manager)
+sudo apt update && sudo apt upgrade glab
+```
+
+## Authentication Issues
+
+### 401 Unauthorized
+
+**Error:**
+```
+failed to get current user: GET https://gitlab.com/api/v4/user: 401 {message: 401 Unauthorized}
+```
+
+**Causes:**
+- Not authenticated
+- Token expired
+- Invalid token
+- Wrong GitLab instance
+
+**Solutions:**
+1. Authenticate:
+   ```bash
+   glab auth login
+   ```
+
+2. Check authentication status:
+   ```bash
+   glab auth status
+   ```
+
+3. Re-authenticate with new token:
+   ```bash
+   glab auth login --hostname gitlab.com --token YOUR_TOKEN
+   ```
+
+4. Verify token has correct scopes (api, read_user, write_repository)
+
+5. For self-hosted GitLab, ensure correct hostname:
+   ```bash
+   glab auth login --hostname gitlab.example.org
+   ```
+
+### Token Permissions
+
+**Error:**
+```
+403 Forbidden
+```
+or
+```
+insufficient permissions
+```
+
+**Causes:**
+- Token lacks required scopes
+- User doesn't have project permissions
+
+**Solutions:**
+1. Create new token with required scopes:
+   - api
+   - read_api
+   - read_user
+   - write_repository
+   - read_repository
+
+2. Verify project access in GitLab web UI
+
+3. Check if project is private and token has access
+
+### Multiple Accounts
+
+**Issue:** Working with multiple GitLab instances
+
+**Solution:**
+glab supports multiple authenticated accounts:
+
+```bash
+# Authenticate with gitlab.com
+glab auth login --hostname gitlab.com
+
+# Authenticate with self-hosted instance
+glab auth login --hostname gitlab.example.org
+
+# Check all authenticated accounts
+glab auth status
+
+# Use specific host for command
+glab mr list -R gitlab.example.org/namespace/project
+```
+
+## Repository Context Issues
+
+### Not a Git Repository
+
+**Error:**
+```
+fatal: not a git repository (or any of the parent directories): .git
+```
+
+**Causes:**
+- Running glab outside a Git repository
+- Git repository not initialized
+
+**Solutions:**
+1. Navigate to a Git repository:
+   ```bash
+   cd /path/to/your/repo
+   ```
+
+2. Or specify repository explicitly:
+   ```bash
+   glab mr list -R owner/repo
+   ```
+
+3. Initialize Git repository if needed:
+   ```bash
+   git init
+   git remote add origin git@gitlab.com:owner/repo.git
+   ```
+
+### Wrong Repository Detected
+
+**Issue:** glab operating on wrong repository
+
+**Solution:**
+1. Check current repository remote:
+   ```bash
+   git remote -v
+   ```
+
+2. Specify correct repository:
+   ```bash
+   glab mr list -R owner/correct-repo
+   ```
+
+3. Update Git remote if wrong:
+   ```bash
+   git remote set-url origin git@gitlab.com:owner/correct-repo.git
+   ```
+
+### 404 Project Not Found
+
+**Error:**
+```
+404 Project Not Found
+```
+
+**Causes:**
+- Repository doesn't exist
+- Wrong namespace/project name
+- No access permissions
+- Wrong GitLab instance
+
+**Solutions:**
+1. Verify repository name:
+   ```bash
+   # Check in GitLab web UI
+   # Correct format: namespace/project
+   ```
+
+2. Check you have access to the project
+
+3. Verify GitLab instance:
+   ```bash
+   glab auth status
+   ```
+
+4. For self-hosted, set correct host:
+   ```bash
+   GITLAB_HOST=gitlab.example.org glab repo view
+   ```
+
+## Merge Request Issues
+
+### Source Branch Already Has MR
+
+**Error:**
+```
+failed to create merge request: source branch already has a merge request
+```
+
+**Cause:**
+- A merge request already exists for this branch
+
+**Solutions:**
+1. List existing MRs to find it:
+   ```bash
+   glab mr list
+   glab mr list --source-branch=$(git branch --show-current)
+   ```
+
+2. View the existing MR:
+   ```bash
+   glab mr view <mr-number>
+   ```
+
+3. Update existing MR instead of creating new one:
+   ```bash
+   glab mr update <mr-number> --title "New title"
+   ```
+
+### Cannot Merge: Conflicts Exist
+
+**Error:**
+```
+Cannot merge: merge conflicts exist
+```
+
+**Solutions:**
+1. Checkout MR locally:
+   ```bash
+   glab mr checkout <mr-number>
+   ```
+
+2. Fetch latest target branch:
+   ```bash
+   git fetch origin main
+   ```
+
+3. Merge or rebase:
+   ```bash
+   git merge origin/main
+   # or
+   git rebase origin/main
+   ```
+
+4. Resolve conflicts and push:
+   ```bash
+   git add .
+   git commit
+   git push
+   ```
+
+### Pipeline Must Succeed
+
+**Error:**
+```
+cannot merge: pipeline must succeed
+```
+
+**Cause:**
+- Project requires successful pipeline before merge
+- Pipeline is failing or pending
+
+**Solutions:**
+1. Check pipeline status:
+   ```bash
+   glab ci status
+   ```
+
+2. View pipeline details:
+   ```bash
+   glab pipeline ci view
+   ```
+
+3. Fix pipeline failures and retry:
+   ```bash
+   glab ci retry
+   ```
+
+4. If project settings allow, force merge (not recommended):
+   ```bash
+   # Only if you have maintainer permissions
+   glab mr merge <mr-number> --when-pipeline-succeeds
+   ```
+
+### Cannot Push to Source Branch
+
+**Error:**
+```
+You cannot push commits to this source branch
+```
+
+**Cause:**
+- MR is from a fork
+- No write access to source repository
+
+**Solution:**
+Ask MR author to make changes, or:
+1. Checkout MR:
+   ```bash
+   glab mr checkout <mr-number>
+   ```
+
+2. Make changes on their fork (requires special permissions)
+
+## Pipeline/CI Issues
+
+### Pipeline Not Found
+
+**Error:**
+```
+pipeline not found
+```
+
+**Causes:**
+- No pipeline exists for current branch
+- Pipeline hasn't started yet
+
+**Solutions:**
+1. Trigger a pipeline:
+   ```bash
+   glab ci run
+   ```
+
+2. Check if .gitlab-ci.yml exists:
+   ```bash
+   ls -la .gitlab-ci.yml
+   ```
+
+3. Verify CI/CD is enabled in project settings
+
+### CI Lint Errors
+
+**Error:**
+```
+.gitlab-ci.yml is invalid
+```
+
+**Solutions:**
+1. Lint locally:
+   ```bash
+   glab ci lint
+   ```
+
+2. Common issues:
+   - YAML syntax errors (tabs vs spaces)
+   - Invalid job names
+   - Missing required fields
+   - Incorrect indentation
+
+3. Use GitLab CI/CD config validation in web UI
+
+4. Check GitLab CI/CD documentation for syntax
+
+### Cannot Download Artifacts
+
+**Error:**
+```
+failed to download artifacts
+```
+
+**Causes:**
+- Artifacts expired
+- Job didn't produce artifacts
+- Permission issues
+
+**Solutions:**
+1. Check if job has artifacts:
+   ```bash
+   glab ci view <pipeline-id>
+   ```
+
+2. Verify artifacts haven't expired (check project settings)
+
+3. Run job again if needed:
+   ```bash
+   glab ci retry
+   ```
+
+## Network and Connection Issues
+
+### Connection Timeout
+
+**Error:**
+```
+dial tcp: i/o timeout
+```
+
+**Causes:**
+- Network connectivity issues
+- Firewall blocking connection
+- GitLab instance down
+
+**Solutions:**
+1. Check network connection:
+   ```bash
+   ping gitlab.com
+   ```
+
+2. Verify GitLab status:
+   ```bash
+   curl -I https://gitlab.com
+   ```
+
+3. Check firewall/proxy settings
+
+4. For self-hosted, verify hostname:
+   ```bash
+   ping gitlab.example.org
+   ```
+
+### SSL Certificate Issues
+
+**Error:**
+```
+x509: certificate signed by unknown authority
+```
+
+**Causes:**
+- Self-signed certificate
+- Corporate proxy
+- Invalid SSL certificate
+
+**Solutions:**
+1. For development/testing only (NOT production):
+   ```bash
+   export GIT_SSL_NO_VERIFY=true
+   ```
+
+2. Add certificate to system trust store (preferred)
+
+3. Configure Git to use specific CA bundle:
+   ```bash
+   git config --global http.sslCAInfo /path/to/cert.pem
+   ```
+
+## Environment Variable Issues
+
+### GITLAB_HOST Not Recognized
+
+**Issue:** Commands still using gitlab.com instead of self-hosted instance
+
+**Solutions:**
+1. Export variable in current shell:
+   ```bash
+   export GITLAB_HOST=gitlab.example.org
+   ```
+
+2. Add to shell profile (~/.bashrc, ~/.zshrc):
+   ```bash
+   echo 'export GITLAB_HOST=gitlab.example.org' >> ~/.bashrc
+   source ~/.bashrc
+   ```
+
+3. Or use flag for each command:
+   ```bash
+   glab mr list -R gitlab.example.org/owner/repo
+   ```
+
+### GITLAB_TOKEN Not Working
+
+**Issue:** Token set but authentication still failing
+
+**Solutions:**
+1. Verify token is exported:
+   ```bash
+   echo $GITLAB_TOKEN
+   ```
+
+2. Ensure no spaces in token:
+   ```bash
+   export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
+   ```
+
+3. Token should not be quoted in export:
+   ```bash
+   # Correct
+   export GITLAB_TOKEN=glpat-xxx
+
+   # Incorrect
+   export GITLAB_TOKEN="glpat-xxx"
+   ```
+
+4. Verify token is valid in GitLab web UI
+
+## Output and Display Issues
+
+### Garbled or Missing Output
+
+**Issue:** Terminal output is corrupted or incomplete
+
+**Solutions:**
+1. Disable glamour styling:
+   ```bash
+   export GLAMOUR_STYLE=notty
+   ```
+
+2. Use plain text output:
+   ```bash
+   glab mr list --output=text
+   ```
+
+3. Update terminal emulator
+
+4. Try different pager:
+   ```bash
+   export PAGER=less
+   ```
+
+### JSON Parsing Errors
+
+**Issue:** Cannot parse JSON output
+
+**Solutions:**
+1. Ensure command supports JSON:
+   ```bash
+   glab mr list --output=json
+   ```
+
+2. Pipe through jq for validation:
+   ```bash
+   glab mr list --output=json | jq '.'
+   ```
+
+3. Check for error messages mixed with JSON
+
+## Performance Issues
+
+### Commands Running Slowly
+
+**Causes:**
+- Large repository
+- Many results being fetched
+- Network latency
+
+**Solutions:**
+1. Limit results:
+   ```bash
+   glab mr list --per-page=10 --page=1
+   ```
+
+2. Use specific filters:
+   ```bash
+   glab mr list --assignee=@me --state=opened
+   ```
+
+3. Disable web browser opening:
+   ```bash
+   glab mr view 123 --web=false
+   ```
+
+## Configuration Issues
+
+### Config File Corruption
+
+**Error:**
+```
+failed to load config
+```
+
+**Solutions:**
+1. Check config file:
+   ```bash
+   cat ~/.config/glab-cli/config.yml
+   ```
+
+2. Backup and recreate:
+   ```bash
+   mv ~/.config/glab-cli/config.yml ~/.config/glab-cli/config.yml.bak
+   glab auth login
+   ```
+
+3. Manually edit config:
+   ```bash
+   vim ~/.config/glab-cli/config.yml
+   ```
+
+## General Troubleshooting Steps
+
+When encountering any error:
+
+1. **Check version:**
+   ```bash
+   glab version
+   ```
+
+2. **Update glab:**
+   ```bash
+   glab check-update
+   ```
+
+3. **Enable verbose output:**
+   ```bash
+   glab <command> --verbose
+   ```
+
+4. **Check authentication:**
+   ```bash
+   glab auth status
+   ```
+
+5. **Verify repository context:**
+   ```bash
+   git remote -v
+   ```
+
+6. **Use --help:**
+   ```bash
+   glab <command> --help
+   ```
+
+7. **Check GitLab API status:**
+   Visit https://status.gitlab.com
+
+8. **Review logs:**
+   ```bash
+   # Check recent commands
+   history | grep glab
+   ```
+
+## Getting Additional Help
+
+If issues persist:
+
+1. Check glab documentation: https://docs.gitlab.com/editor_extensions/gitlab_cli/
+2. Search glab issues: https://gitlab.com/gitlab-org/cli/-/issues
+3. Create a new issue with:
+   - glab version
+   - Operating system
+   - Full error message
+   - Steps to reproduce
+   - Output with --verbose flag

package/framework/skills/great-interface/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: great-interface
+description: >-
+  Build, explain, review, and refine product interfaces across accessibility, layout,
+  writing, typography, color, UI polish, holistic review, change review, and design variants.
+  Use when creating frontend interfaces, reviewing interface quality, explaining how an
+  interface works, or comparing UI directions.
+---
+
+# Great Interface
+
+Use the domain references below as the sources of truth. Load the smallest set that covers
+the request, except for a holistic review, which loads every applicable review domain.
+
+## Build and refine
+
+- Accessibility: [better-accessibility.md](references/better-accessibility.md)
+- Layout: [better-layout.md](references/better-layout.md)
+- Writing: [better-writing.md](references/better-writing.md)
+- Typography: [better-typography.md](references/better-typography.md)
+- Colors: [better-colors.md](references/better-colors.md)
+- UI polish and motion: [better-ui.md](references/better-ui.md)
+
+## Review
+
+- Holistic screen or flow review: [better-interface.md](references/better-interface.md)
+- Change, branch, or pull request review: [interface-review.md](references/interface-review.md)
+
+## Explore alternatives
+
+- Explain how an interface or effect was built: [explain-interface.md](references/explain-interface.md)
+- Build and compare multiple UI directions: [variant.md](references/variant.md)
+
+## Ownership
+
+Do not duplicate rules across domains. Accessibility owns keyboard support, focus, ARIA,
+semantic structure, hit areas, announcements, and reduced motion. Layout owns grouping,
+spacing, responsive structure, and spatial RTL. Writing owns interface copy. Typography owns
+how text renders and wraps. Colors owns palette systems and color measurement. UI owns
+surfaces, icons, and visual motion. The review references own orchestration and reporting.
+
+When domains overlap, report or apply the rule in the owning domain and mention secondary
+effects only where useful.