gitcode-issue-workflow

---

name: gitcode-issue-workflow description: > End-to-end GitCode issue workflow covering issue pickup, analysis, code modification, and PR submission. Use when user asks to handle/fix/resolve a GitCode issue, or when working on issue-driven development for GitCode repositories. Triggers on phrases like "接取 issue", "处理 issue", "修复 issue", "fix issue", "handle issue", "resolve issue", "提交 PR", "create PR for issue". Requires gitcode CLI (GitCode CLI) and git. NOT for code review (use code-review skill), issue triage without code changes, or non-GitCode platforms.

---

GitCode Issue Workflow

End-to-end workflow: Issue → Analysis → Code Fix → PR Submission.

Prerequisites

gitcode CLI: GitCode CLI (similar to GitHub's gh). Source: https://github.com/codeasier/gitcode-cli

git: Standard git CLI

GitCode Token: Stored in MEMORY.md or provided by user

Local repo: User must confirm the local repository path

CLI command name:

gitcode — full command name, works on all platforms (recommended on Windows)

gc — short alias, works on macOS/Linux (conflicts with PowerShell Get-Content on Windows)

gitcode CLI detection (follow this order): 1. Try gitcode --version first (recommended, works everywhere) 2. If not found, try gc --version (macOS/Linux fallback) 3. If neither found, ask user for the full path to the executable 4. If not installed, prompt to install from https://github.com/codeasier/gitcode-cli

gitcode CLI authentication check: After confirming the CLI is installed, try a lightweight command to verify authentication (e.g., gitcode issue view 1 --repo /). If it returns a token-related error like Invalid header parameter: private-token, required, the CLI is not authenticated.

Stop and prompt the user to authenticate first:

gitcode auth login

Or if they have a token, use --with-token (not --token):

echo  | gitcode auth login --with-token

Windows note: If the CLI outputs emoji characters and throws UnicodeEncodeError: 'gbk' codec can't encode character, set the Python IO encoding before running CLI commands:

$env:PYTHONIOENCODING="utf-8"
gitcode issue view  --repo /

Do not proceed with the workflow until authentication is successful.

Windows note: On PowerShell, gc is an alias for Get-Content. Always use gitcode on Windows.

6-Step Workflow

Step 1: Fetch & Read Issue

Fetch the issue using gitcode CLI:

gitcode issue view  --repo /
gitcode issue view  --repo / --comments

(gc can be used as shorthand on macOS/Linux, e.g., gc issue view ...)

If the CLI returns an authentication error (e.g., Invalid header parameter: private-token, required): 1. Check gitcode auth status 2. If not authenticated, prompt the user to run gitcode auth login and stop the workflow 3. If the user prefers not to use the CLI for authentication, fall back to the GitCode API with an explicit token:

   curl -s "https://api.gitcode.com/api/v5/repos///issues/?access_token="
   curl -s "https://api.gitcode.com/api/v5/repos///issues//comments?access_token="
   

Parse and present to user:

Issue title, state, author, assignees, labels

Problem description (each numbered point)

Comments from maintainers (especially assignment decisions and clarifications)

Step 2: Confirm Local Repository

Must confirm with user before proceeding:

1. Ask user for the local repository path (or confirm if already known) 2. Verify the repo exists and is on the correct branch:

cd 
git status
git log --oneline -3

3. Pull latest code from the target branch (usually master):

git pull  

⚠️ Constraints:

Never assume the local repo path — always confirm with user

Verify working tree is clean before starting work

Identify which remote is upstream (the target org repo) vs personal fork

Step 3: Read & Analyze Target Files

Read the files that need modification based on the issue description:

# Use read tool to examine the file contents
read 

Analysis requirements:

Understand the current structure and content of files to be modified

Cross-reference with issue requirements and maintainer comments

Identify the minimal change set needed

Step 4: Propose Changes

⚠️ Must get user approval before modifying any files.

Present to the user: 1. Modification target: Which file(s) will be changed 2. Modification approach: What will be changed and why 3. Expected diff: Show the before/after comparison in diff format

- old content
+ new content

4. Rationale: How this addresses the issue requirements

Wait for user confirmation before proceeding to Step 5.

If user requests adjustments, revise the proposal and re-present.

Step 5: Apply Changes

After user approval, apply the changes:

# Edit the file using edit tool
edit  oldText -> newText

Verify the changes:

cd 
git diff 

Show the diff output to user for final confirmation.

Step 6: Create Branch, Commit & Submit PR

This step involves multiple sub-steps. Follow them in strict order.

#### 6.1 Create Branch

Branch naming format: [type]_[YYYYMMDD]_[brief_description]

type: doc, fix, feat, refactor, test, chore, etc.

date: Current date in YYYYMMDD format

description: 1-2 English words separated by underscores

cd 
git checkout -b 

Examples:

doc_20260424_contributing_guide

fix_20260424_null_check

feat_20260424_export_csv

#### 6.2 Commit

Commit message format: type: [detailed description]

git add 
git commit -m "(): "

Examples:

docs(readme): elevate contributing guide to standalone section

fix(parser): add null check for empty input

feat(export): add CSV export support

#### 6.3 Push to Personal Fork

⚠️ Critical constraints:

Must ask user which remote to push to — never assume

Never push directly to the upstream/organization repository

List available remotes for user to choose:

git remote -v

Then push:

git push  

#### 6.4 Create PR (Merge Request)

Method 1: gitcode CLI (preferred)

gitcode pr create -R / \
  --fork / \
  --head  \
  --base  \
  --title "" \
  --body ""

On macOS/Linux, gc is a valid shorthand: gc pr create ...

⚠️ Must ask user for the target branch (e.g., master, main, develop) if not already known. Do not assume.

PR body template:

## PR描述 (What this PR does / why we need it?)
面向用户的变更 (Does this PR introduce _any_ user-facing change)?
功能验证 (How was this patch tested?)

Method 2: GitCode API (fallback if gc CLI fails)

See references/gitcode-api.md for the API endpoint and parameters.

curl -s -X POST "https://api.gitcode.com/api/v5/repos///pulls?access_token=" \
  -H "Content-Type: application/json" \
  -d @

Payload structure:

{
  "title": "",
  "body": "",
  "head": ":",
  "base": "",
  "fork_path": "/"
}

Method 3: Manual (last resort)

If both gc CLI and API fail, provide the user with the manual creation URL:

https://gitcode.com///merge_requests/new?source_branch=

And the PR description text for them to paste.

#### 6.5 Confirm & Report

After PR creation, present a summary:

| Item | Value | |:---|:---| | PR URL | | | PR Number | # | | Source | /: | | Target | /: | | Linked Issue | # | | Status | Opened |

Key Constraints

Safety Rules

1. Never push to upstream/organization repos directly — always use personal fork 2. Never modify files without user approval — always show proposed changes first 3. Never assume repository paths — always confirm with user 4. Never assume target branch — always ask if unknown 5. Never assume push remote — always list remotes and ask user to choose 6. All external write operations require explicit user confirmation

Git Workflow Rules

1. Working tree must be clean before creating a new branch 2. Branch must be created from the latest target branch code 3. Commit messages must follow the format: type: [description] 4. Branch names must follow the format: [type]_[YYYYMMDD]_[brief_description] 5. Always verify changes with git diff before committing

Asking vs Doing

| Action | Ask First? | |:---|:---| | Read files, check git status | ❌ Just do it | | Fetch issue details | ❌ Just do it | | Propose changes | ❌ Present proposal | | Modify files | ✅ Wait for approval | | Push to remote | ✅ Ask which remote | | Create PR | ✅ Ask target branch if unknown | | Post issue comments | ✅ Always confirm |

Temp File Management

All temporary files generated during the workflow must be stored in temp/ directory under the workspace:

workspace/temp/
├── *.md          # Downloaded files for review
├── *.json        # API payloads
└── *             # Other temp files

⚠️ Clean up temp/ directory after workflow completion:

Remove-Item -Recurse -Force temp/  # Windows
rm -rf temp/                        # Linux/macOS

gitcode CLI: GitCode CLI (similar to GitHub's gh). Source: https://github.com/codeasier/gitcode-cli

git: Standard git CLI

GitCode Token: Stored in MEMORY.md or provided by user

Local repo: User must confirm the local repository path

CLI command name:

gitcode — full command name, works on all platforms (recommended on Windows)

gc — short alias, works on macOS/Linux (conflicts with PowerShell Get-Content on Windows)

gitcode CLI detection (follow this order): 1. Try gitcode --version first (recommended, works everywhere) 2. If not found, try gc --version (macOS/Linux fallback) 3. If neither found, ask user for the full path to the executable 4. If not installed, prompt to install from https://github.com/codeasier/gitcode-cli

gitcode CLI authentication check: After confirming the CLI is installed, try a lightweight command to verify authentication (e.g., gitcode issue view 1 --repo /). If it returns a token-related error like Invalid header parameter: private-token, required, the CLI is not authenticated.

Stop and prompt the user to authenticate first:

gitcode auth login

Or if they have a token, use --with-token (not --token):

echo  | gitcode auth login --with-token

Windows note: If the CLI outputs emoji characters and throws UnicodeEncodeError: 'gbk' codec can't encode character, set the Python IO encoding before running CLI commands:

$env:PYTHONIOENCODING="utf-8"
gitcode issue view  --repo /

Do not proceed with the workflow until authentication is successful.

Windows note: On PowerShell, gc is an alias for Get-Content. Always use gitcode on Windows.