name	file-issue
description	File a bug report or feature request to a project's GitHub repository
group	github
keywords	["github","issues","bug report","feature request","bug","feature","filing issues"]
version	1.0.0
author	docent

File Issue Runbook

This runbook files bug reports, feature requests, questions, or documentation issues to a project's GitHub repository using the gh CLI.

Purpose

Standardize issue creation with proper formatting, required information, and appropriate labels. Works with any project configured in .docent/config.yaml.

Prerequisites

gh CLI installed and authenticated (gh auth status)
Project configured in .docent/config.yaml with repository information
Network connectivity to GitHub

Variables

This runbook accepts the following variables:

project: Which project to file against (default: current project)
type: bug | feature | question | documentation
title: Issue title (required)
description: Issue body (required)

Additional type-specific variables:

For bugs:

actual_behavior: What's happening now
expected_behavior: What should happen
reproduction_steps: How to reproduce the bug

For features:

use_case: Why this feature is needed
suggested_solution: Proposed implementation (optional)

For documentation:

location: Where documentation is unclear/missing
suggestion: Proposed improvement

Procedure

Step 1: Resolve Project Repository

Action: Determine which GitHub repository to file against

From .docent/config.yaml:

projects:
  docent:
    repo: tnez/docent
  my-app:
    repo: user/my-app

Resolution logic:

If project variable provided → use that project's repo
If project = "current" or not provided → detect from git remote
If no config and no git remote → error (cannot determine repo)

Commands:

# Get current repo from git remote
git remote get-url origin | sed 's/.*github.com[:/]\(.*\)\.git/\1/'

# Validate repo exists
gh repo view <owner/repo> --json name

Validation:

Repository identifier is in owner/repo format
Repository exists and is accessible
User has permission to create issues

Step 2: Format Issue Based on Type

Action: Generate appropriate issue template based on type

Bug Report Format

## Description

{{description}}

## Current Behavior

{{actual_behavior}}

## Expected Behavior

{{expected_behavior}}

## Steps to Reproduce

{{reproduction_steps}}

## Environment

- OS: {{os}}
- Version: {{version}}

---

Filed via [docent](https://github.com/tnez/docent)

Feature Request Format

## Feature Description

{{description}}

## Use Case

{{use_case}}

## Suggested Solution

{{suggested_solution}}

---

Filed via [docent](https://github.com/tnez/docent)

Question Format

## Question

{{description}}

---

Filed via [docent](https://github.com/tnez/docent)

Documentation Issue Format

## Documentation Issue

{{description}}

## Location

{{location}}

## Suggested Improvement

{{suggestion}}

---

Filed via [docent](https://github.com/tnez/docent)

Step 3: Add Appropriate Labels

Action: Determine labels based on issue type

Label mapping:

bug → bug
feature → enhancement, feature-request
question → question
documentation → documentation

Additional labels (if detectable):

Project area (e.g., mcp, templates, documentation)
Priority (e.g., priority: high if certain keywords present)

Commands:

# Check available labels for repository
gh label list --repo <owner/repo>

Step 4: Create GitHub Issue

Action: File the issue using gh issue create

Commands:

# Create issue with body from file
gh issue create \
  --repo <owner/repo> \
  --title "<title>" \
  --body "<formatted body>" \
  --label "<labels>"

# Example for bug:
gh issue create \
  --repo tnez/docent \
  --title "Bootstrap fails with permission error" \
  --body "$(cat issue-body.md)" \
  --label "bug"

Validation:

Issue created successfully
Issue number returned
Issue URL accessible

Step 5: Report Success

Action: Provide confirmation with issue link

Success Message:

✅ Issue filed successfully!

Issue #123: <title>
URL: https://github.com/<owner/repo>/issues/123

The issue has been created with:
  - Type: <type>
  - Labels: <labels>
  - Status: Open

You can view and track the issue at the URL above.

Additional actions:

Copy issue URL to clipboard (if supported)
Optionally log to .docent/journals/ for tracking

Examples

Example 1: File Bug in Docent

Invocation:

/docent:act file issue in docent: bootstrap fails on Windows with permission error

(Agent interprets and extracts):
- project: docent
- type: bug
- title: "Bootstrap fails on Windows with permission error"
- description: "When running bootstrap on Windows, permission denied error occurs"

Generated issue:

Repo: tnez/docent
Title: "Bootstrap fails on Windows with permission error"
Labels: bug
Body: Formatted bug report

Example 2: Feature Request for Current Project

Invocation:

/docent:act file feature request: add dark mode support

(Agent interprets):
- project: current (detected from git remote)
- type: feature
- title: "Add dark mode support"
- use_case: Better UX for users working at night

Generated issue:

Repo: user/my-app (from git remote)
Title: "Add dark mode support"
Labels: enhancement, feature-request
Body: Formatted feature request

Example 3: Documentation Issue

Invocation:

/docent:act file documentation issue for docent: getting started guide is outdated

(Agent interprets):
- project: docent
- type: documentation
- title: "Getting started guide is outdated"
- location: docs/guides/getting-started.md

Generated issue:

Repo: tnez/docent
Title: "Getting started guide is outdated"
Labels: documentation
Body: Formatted documentation issue

Error Handling

gh CLI Not Authenticated

Symptoms: gh issue create fails with authentication error

Fix:

# Authenticate with GitHub
gh auth login

# Follow prompts to authenticate

Validation: gh auth status shows authenticated

Repository Not Found

Symptoms: Cannot find repository from config or git remote

Fix:

Check .docent/config.yaml has correct repo
Verify git remote: git remote get-url origin
Provide explicit project parameter

Permission Denied

Symptoms: Cannot create issues in repository

Fix:

Verify you have access to the repository
Check repository settings allow issue creation
Use gh auth refresh to update permissions

Network Error

Symptoms: Cannot reach GitHub

Fix:

Check internet connectivity
Verify GitHub status: https://www.githubstatus.com
Retry after connectivity restored

Configuration

Add projects to .docent/config.yaml:

projects:
  docent:
    repo: tnez/docent
    default_labels:
      - via-docent

  my-app:
    repo: user/my-app
    default_labels:
      - automated

  work-project:
    repo: company/project
    default_labels:
      - from-docent
      - needs-triage

Options:

repo: GitHub repository in owner/repo format (required)
default_labels: Labels to add to all issues (optional)

Validation

After filing issue:

Issue exists at provided URL
Issue has correct title and body
Labels are applied correctly
Issue is searchable in GitHub

Notes

Issues are filed with attribution: "Filed via docent"
Attribution helps track which issues came from docent for analytics
Users can edit issues after filing via GitHub UI
Issue URLs are permanent (even if issue is closed/deleted)
Consider logging filed issues to journal for personal tracking

Advanced Usage

Batch Issue Filing

File multiple related issues:

/docent:act file issues for planned features:
1. Add export functionality
2. Implement search
3. Create user dashboard

Agent can interpret and file 3 separate feature requests

Issue Templates

Projects can define custom templates in .docent/templates/issue-*.md that override default formats

Auto-labeling

Configure intelligent labeling based on content:

projects:
  my-app:
    repo: user/my-app
    auto_labels:
      - pattern: "auth|login|password"
        labels: ["area: auth"]
      - pattern: "slow|performance|speed"
        labels: ["performance"]

Related Runbooks

health-check - Find issues to file before they become bugs
code-review - Review changes before filing improvement issues