Phase 3: Add decision trees and cross-linking (#16)

- Added decision trees to root skill:
  * "Should I create an MR or work on an issue first?"
  * "Which CI command should I use?" (pipeline vs job level)
  * "Clone or fork?" (access and use case guidance)
  * "Project vs group labels?" (scope decision tree)
- Enhanced glab-label with decision tree and workflows
- Enhanced glab-job with pipeline vs job decision tree
- Added "Related Skills" sections to all major skills:
  * glab-mr → glab-issue, glab-ci, scripts
  * glab-issue → glab-mr, glab-label, glab-milestone, glab-iteration, scripts
  * glab-ci → glab-job, glab-schedule, glab-variable, glab-mr, scripts
  * glab-repo → glab-auth, glab-ssh-key, glab-deploy-key, glab-config, glab-variable, scripts
  * glab-auth → glab-config, glab-ssh-key, glab-gpg-key, glab-repo
  * glab-label → glab-issue, glab-mr, scripts
  * glab-job → glab-ci, glab-variable, glab-schedule, scripts
- All cross-references include relevant automation scripts

Addresses #15 Phase 3 objectives:
✅ Root skill enhanced with decision trees and navigation
✅ 4+ decision trees added to guide command selection
✅ Cross-links added between related skills
✅ "Related Skills" sections improve discoverability
✅ Decision trees provide actionable guidance

Improvements:
- Better skill discovery through cross-linking
- Decision trees reduce "which command?" confusion
- Clear guidance on pipeline vs job, clone vs fork, project vs group labels
- Scripts referenced in related skills for automation opportunities

Co-authored-by: Ubuntu <ubuntu@vps-9755df38.vps.ovh.us>

SKILL.md

@@ -140,3 +140,106 @@ glab ci trace <job-id>
 # Retry failed job
 glab ci retry <job-id>
 ```
+
+## Decision Trees
+
+### "Should I create an MR or work on an issue first?"
+
+```
+Need to track work?
+├─ Yes → Create issue first (glab issue create)
+│         Then: glab mr for <issue-id>
+└─ No → Direct MR (glab mr create --fill)
+```
+
+**Use `glab issue create` + `glab mr for` when:**
+- Work needs discussion/approval before coding
+- Tracking feature requests or bugs
+- Sprint planning and assignment
+- Want issue to auto-close when MR merges
+
+**Use `glab mr create` directly when:**
+- Quick fixes or typos
+- Working from existing issue
+- Hotfixes or urgent changes
+
+### "Which CI command should I use?"
+
+```
+What do you need?
+├─ Overall pipeline status → glab ci status
+├─ Visual pipeline view → glab ci view
+├─ Specific job logs → glab ci trace <job-id>
+├─ Download build artifacts → glab ci artifact <ref> <job-name>
+├─ Validate config file → glab ci lint
+├─ Trigger new run → glab ci run
+└─ List all pipelines → glab ci list
+```
+
+**Quick reference:**
+- Pipeline-level: `glab ci status`, `glab ci view`, `glab ci run`
+- Job-level: `glab ci trace`, `glab job retry`, `glab job view`
+- Artifacts: `glab ci artifact` (by pipeline) or job artifacts via `glab job`
+
+### "Clone or fork?"
+
+```
+What's your relationship to the repo?
+├─ You have write access → glab repo clone group/project
+├─ Contributing to someone else's project:
+│   ├─ One-time contribution → glab repo fork + work + MR
+│   └─ Ongoing contributions → glab repo fork, then sync regularly
+└─ Just reading/exploring → glab repo clone (or view --web)
+```
+
+**Fork when:**
+- You don't have write access to the original repo
+- Contributing to open source projects
+- Experimenting without affecting the original
+- Need your own copy for long-term work
+
+**Clone when:**
+- You're a project member with write access
+- Working on organization/team repositories
+- No need for a personal copy
+
+### "Project vs group labels?"
+
+```
+Where should the label live?
+├─ Used across multiple projects → glab label create --group <group>
+└─ Specific to one project → glab label create (in project directory)
+```
+
+**Group-level labels:**
+- Consistent labeling across organization
+- Examples: priority::high, type::bug, status::blocked
+- Managed centrally, inherited by projects
+
+**Project-level labels:**
+- Project-specific workflows
+- Examples: needs-ux-review, deploy-to-staging
+- Managed by project maintainers
+
+## Related Skills
+
+**MR and Issue workflows:**
+- Start with `glab-issue` to create/track work
+- Use `glab-mr` to create MR that closes issue
+- Script: `scripts/create-mr-from-issue.sh` automates this
+
+**CI/CD debugging:**
+- Use `glab-ci` for pipeline-level operations
+- Use `glab-job` for individual job operations
+- Script: `scripts/ci-debug.sh` for quick failure diagnosis
+
+**Repository operations:**
+- Use `glab-repo` for repository management
+- Use `glab-auth` for authentication setup
+- Script: `scripts/sync-fork.sh` for fork synchronization
+
+**Configuration:**
+- Use `glab-auth` for initial authentication
+- Use `glab-config` to set defaults and preferences
+- Use `glab-alias` for custom shortcuts
+

glab-auth/SKILL.md

@@ -91,3 +91,15 @@ See [references/commands.md](references/commands.md) for detailed flag documenta
 - `configure-docker` - Configure Docker to use GitLab registry
 - `docker-helper` - Docker credential helper
 - `dpop-gen` - Generate DPoP token
+
+## Related Skills
+
+**Initial setup:**
+- After authentication, see `glab-config` to set CLI defaults
+- See `glab-ssh-key` for SSH key management
+- See `glab-gpg-key` for commit signing setup
+
+**Repository operations:**
+- See `glab-repo` for cloning repositories
+- Authentication required before first clone/push
+

glab-ci/SKILL.md

@@ -135,6 +135,23 @@ glab ci delete <pipeline-id>
 - Check artifact uploads: Verify paths in job output
 - Validate config: `glab ci lint`
 
+## Related Skills
+
+**Job-specific operations:**
+- See `glab-job` for individual job commands (list, view, retry, cancel)
+- Use `glab-ci` for pipeline-level, `glab-job` for job-level
+
+**Pipeline triggers and schedules:**
+- See `glab-schedule` for scheduled pipeline automation
+- See `glab-variable` for managing CI/CD variables
+
+**MR integration:**
+- See `glab-mr` for merge operations
+- Use `glab mr merge --when-pipeline-succeeds` for CI-gated merges
+
+**Automation:**
+- Script: `scripts/ci-debug.sh` for quick failure diagnosis
+
 ## Command reference
 
 For complete command documentation and all flags, see [references/commands.md](references/commands.md).

glab-issue/SKILL.md

@@ -115,6 +115,21 @@ git commit -m "Fix login bug
 Closes #456"
 ```
 
+## Related Skills
+
+**Creating MRs from issues:**
+- See `glab-mr` for merge request operations
+- Use `glab mr for <issue-id>` to create MR that closes issue
+- Script: `scripts/create-mr-from-issue.sh` automates branch creation + draft MR
+
+**Label management:**
+- See `glab-label` for creating and managing labels
+- Script: `scripts/batch-label-issues.sh` for bulk labeling operations
+
+**Project planning:**
+- See `glab-milestone` for release planning
+- See `glab-iteration` for sprint/iteration management
+
 ## Command reference
 
 For complete command documentation and all flags, see [references/commands.md](references/commands.md).

glab-job/SKILL.md

@@ -5,32 +5,117 @@ description: Work with individual CI/CD jobs including view, retry, cancel, trac
 
 # glab job
 
-## Overview
-
-```
-
-  Work with GitLab CI/CD jobs.                                                                                          
-         
-  USAGE  
-         
-    glab job <command> [command] [--flags]  
-            
-  COMMANDS  
-            
-    artifact <refName> <jobName> [--flags]  Download all artifacts from the last pipeline.
-         
-  FLAGS  
-         
-    -h --help                               Show help for this command.
-    -R --repo                               Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL.
-```
+Work with individual CI/CD jobs.
 
 ## Quick start
 
 ```bash
-glab job --help
+# View job details
+glab job view <job-id>
+
+# Download job artifacts
+glab job artifact main build-job
+
+# Retry a failed job
+glab ci retry <job-id>
+
+# View job logs
+glab ci trace <job-id>
 ```
 
-## Subcommands
+## Decision: Pipeline vs Job Commands?
 
-See [references/commands.md](references/commands.md) for full `--help` output.
+```
+What level are you working at?
+├─ Entire pipeline (all jobs)
+│  └─ Use glab-ci commands:
+│     ├─ glab ci status     (pipeline status)
+│     ├─ glab ci view       (all jobs in pipeline)
+│     ├─ glab ci run        (trigger new pipeline)
+│     └─ glab ci cancel     (cancel entire pipeline)
+│
+└─ Individual job
+   └─ Use glab-job or glab ci job commands:
+      ├─ glab ci trace <job-id>    (job logs)
+      ├─ glab ci retry <job-id>    (retry one job)
+      ├─ glab job view <job-id>    (job details)
+      └─ glab job artifact <ref> <job> (job artifacts)
+```
+
+**Use `glab ci` (pipeline-level) when:**
+- Checking overall build status
+- Viewing all jobs in a pipeline
+- Triggering new pipeline runs
+- Validating `.gitlab-ci.yml`
+
+**Use `glab job` (job-level) when:**
+- Debugging a specific failed job
+- Downloading artifacts from a specific job
+- Retrying individual jobs (not entire pipeline)
+- Viewing detailed job information
+
+## Common workflows
+
+### Debugging a failed job
+
+1. **Find the failed job:**
+   ```bash
+   glab ci view  # Shows all jobs, highlights failures
+   ```
+
+2. **View job logs:**
+   ```bash
+   glab ci trace <job-id>
+   ```
+
+3. **Retry the job:**
+   ```bash
+   glab ci retry <job-id>
+   ```
+
+### Working with artifacts
+
+**Download artifacts from specific job:**
+```bash
+glab job artifact main build-job
+```
+
+**Download artifacts from latest successful run:**
+```bash
+glab job artifact main build-job --artifact-type job
+```
+
+### Job monitoring
+
+**Watch job logs in real-time:**
+```bash
+glab ci trace <job-id>  # Follows logs until completion
+```
+
+**Check specific job status:**
+```bash
+glab job view <job-id>
+```
+
+## Related Skills
+
+**Pipeline operations:**
+- See `glab-ci` for pipeline-level commands
+- Use `glab ci view` to see all jobs in a pipeline
+- Script: `scripts/ci-debug.sh` for automated failure diagnosis
+
+**CI/CD configuration:**
+- See `glab-variable` for managing job variables
+- See `glab-schedule` for scheduled job runs
+
+## Command reference
+
+For complete command documentation and all flags, see [references/commands.md](references/commands.md).
+
+**Available commands:**
+- `artifact` - Download job artifacts
+- `view` - View job details
+- Most job operations use `glab ci <command> <job-id>`:
+  - `glab ci trace <job-id>` - View logs
+  - `glab ci retry <job-id>` - Retry job
+  - `glab ci cancel <job-id>` - Cancel job

glab-label/SKILL.md

@@ -5,36 +5,103 @@ description: Manage GitLab labels including create, list, update, and delete ope
 
 # glab label
 
-## Overview
-
-```
-
-  Manage labels on remote.                                                                                              
-         
-  USAGE  
-         
-    glab label <command> [command] [--flags]  
-            
-  COMMANDS  
-            
-    create [--flags]  Create labels for a repository or project.
-    delete [--flags]  Delete labels for a repository or project.
-    edit [--flags]    Edit group or project label.
-    get <label-id>    Returns a single label specified by the ID.
-    list [--flags]    List labels in the repository.
-         
-  FLAGS  
-         
-    -h --help         Show help for this command.
-    -R --repo         Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL.
-```
+Manage labels at project and group level.
 
 ## Quick start
 
 ```bash
-glab label --help
+# Create project label
+glab label create --name bug --color "#FF0000"
+
+# Create group label
+glab label create --group my-group --name priority::high --color "#FF6B00"
+
+# List labels
+glab label list
+
+# Update label
+glab label edit bug --color "#CC0000" --description "Software defects"
+
+# Delete label
+glab label delete bug
 ```
 
-## Subcommands
+## Decision: Project vs Group Labels?
 
-See [references/commands.md](references/commands.md) for full `--help` output.
+```
+Where should this label live?
+├─ Used across multiple projects in a group
+│  └─ Group-level: glab label create --group <group> --name <label>
+└─ Specific to one project
+   └─ Project-level: glab label create --name <label>
+```
+
+**Use group-level labels when:**
+- You want consistent labeling across all projects in a group
+- Managing organization-wide workflows
+- Examples: `priority::high`, `type::bug`, `status::blocked`
+- Reduces duplication and ensures consistency
+
+**Use project-level labels when:**
+- Label is specific to project workflow
+- Team wants control over their own labels
+- Examples: `needs-ux-review`, `deploy-to-staging`, `legacy-code`
+
+## Common workflows
+
+### Creating a label taxonomy
+
+**Set up priority labels (group-level):**
+```bash
+glab label create --group engineering --name "priority::critical" --color "#FF0000"
+glab label create --group engineering --name "priority::high" --color "#FF6B00"
+glab label create --group engineering --name "priority::medium" --color "#FFA500"
+glab label create --group engineering --name "priority::low" --color "#FFFF00"
+```
+
+**Set up type labels (group-level):**
+```bash
+glab label create --group engineering --name "type::bug" --color "#FF0000"
+glab label create --group engineering --name "type::feature" --color "#00FF00"
+glab label create --group engineering --name "type::maintenance" --color "#0000FF"
+```
+
+### Managing project-specific labels
+
+**Create workflow labels:**
+```bash
+glab label create --name "needs-review" --color "#428BCA"
+glab label create --name "ready-to-merge" --color "#5CB85C"
+glab label create --name "blocked" --color "#D9534F"
+```
+
+### Bulk operations
+
+**List all labels to review:**
+```bash
+glab label list --per-page 100 > labels.txt
+```
+
+**Delete deprecated labels:**
+```bash
+glab label delete old-label-1
+glab label delete old-label-2
+```
+
+## Related Skills
+
+**Using labels:**
+- See `glab-issue` for applying labels to issues
+- See `glab-mr` for applying labels to merge requests
+- Script: `scripts/batch-label-issues.sh` for bulk labeling
+
+## Command reference
+
+For complete command documentation and all flags, see [references/commands.md](references/commands.md).
+
+**Available commands:**
+- `create` - Create label (project or group)
+- `list` - List labels
+- `edit` - Update label properties
+- `delete` - Delete label
+- `get` - View single label details

glab-mr/SKILL.md

@@ -118,6 +118,20 @@ glab mr merge 123
 - Close old MR if obsolete: `glab mr close <id>`
 - Or update existing: `glab mr update <id> --title "New title"`
 
+## Related Skills
+
+**Working with issues:**
+- See `glab-issue` for creating/managing issues
+- Use `glab mr for <issue-id>` to create MR linked to issue
+- Script: `scripts/create-mr-from-issue.sh` automates branch + MR creation
+
+**CI/CD integration:**
+- See `glab-ci` for pipeline status before merging
+- Use `glab mr merge --when-pipeline-succeeds` for auto-merge
+
+**Automation:**
+- Script: `scripts/mr-review-workflow.sh` for automated review + test workflow
+
 ## Command reference
 
 For complete command documentation and all flags, see [references/commands.md](references/commands.md).

glab-repo/SKILL.md

@@ -182,6 +182,20 @@ glab repo list --mine            # Only repos you own
 - Check you have enough disk space
 - Large groups may time out - clone specific repos instead
 
+## Related Skills
+
+**Authentication and access:**
+- See `glab-auth` for login and authentication setup
+- See `glab-ssh-key` for SSH key management
+- See `glab-deploy-key` for deployment authentication
+
+**Project configuration:**
+- See `glab-config` for CLI defaults and settings
+- See `glab-variable` for CI/CD variables
+
+**Fork synchronization:**
+- Script: `scripts/sync-fork.sh` automates upstream sync
+
 ## Command reference
 
 For complete command documentation and all flags, see [references/commands.md](references/commands.md).