---
name: pre-commit-check
description: "MANDATORY pre-commit validation executor. Runs all required checks before any commit. NOT optional - must be invoked before every git add/commit/PR."
version: "2.0.0"
author: "SublinkPro Team"
user-invocable: true
mandatory: true
enforcement-level: "blocking"
---

# Pre-Commit Check Skill

**🛑 MANDATORY VALIDATION EXECUTOR 🛑**

This skill is **NOT** a suggestion or checklist. It is a **MANDATORY EXECUTION REQUIREMENT**.

## Critical Rules

1. **Invoke this skill BEFORE any `git add`, `git commit`, or PR creation**
2. **Execute ALL applicable validation commands**
3. **Fix ALL failures before proceeding**
4. **Document what was validated in commit message**
5. **Stage changes only after validation passes**
6. **Present to user for final verification (do NOT auto-commit)**

## When to Use This Skill

**MANDATORY** invocation before:
- Any `git add` command
- Any `git commit` command
- Any `gh pr create` or PR update command
- Declaring work "complete", "done", or "finished"
- User requests commit (even if they say "skip checks")

**This skill is BLOCKING** - you cannot proceed to commit without invoking it and ensuring all checks pass.

## Skill Execution Protocol

When this skill is invoked, you **MUST** follow this exact sequence:

### Step 1: Identify Changed Files

```bash
git status --short
git diff --name-only
git diff --cached --name-only
```

Categorize changes:
- [ ] Backend files (*.go)
- [ ] Frontend files (webs/*)
- [ ] Documentation files (*.md)
- [ ] Configuration files (config.yaml, .env.example, etc.)
- [ ] Mixed (multiple categories)

### Step 2: Execute Backend Validation (if .go files changed)

#### 2.1 Format Check
```bash
gofmt -l $(find . -name "*.go" -not -path "./vendor/*" -not -path "./webs/*" -not -path "./.git/*")
```

**If output is not empty**:
```bash
gofmt -w $(find . -name "*.go" -not -path "./vendor/*" -not -path "./webs/*" -not -path "./.git/*")
```

**Verify**:
```bash
gofmt -l $(find . -name "*.go" -not -path "./vendor/*" -not -path "./webs/*" -not -path "./.git/*")
```

**BLOCKING**: Must return empty output (all files formatted).

#### 2.2 Lint Check
```bash
golangci-lint run
```

**BLOCKING**: Must exit with status 0.

**If fails**: Read the errors, fix them, and re-run. Do NOT proceed until clean.

#### 2.3 Test Execution
```bash
go test ./...
```

**BLOCKING**: Must exit with status 0 (all tests pass).

**If fails**: Read the test output, fix the failing tests or code, and re-run. Do NOT proceed until green.

### Step 3: Execute Frontend Validation (if webs/* files changed)

#### 3.1 Lint Check
```bash
cd webs && yarn run lint
```

**BLOCKING**: Must exit with status 0.

**If fails**: Try auto-fix first:
```bash
cd webs && yarn run lint:fix
cd webs && yarn run prettier
```

Then re-run `yarn run lint`. Do NOT proceed until clean.

#### 3.2 Build Check (if applicable)

**Run build if changes affect**:
- Routing configuration (`src/routes/*`)
- Asset paths or imports (`src/assets/*`, `public/*`)
- Base path behavior (`SUBLINK_WEB_BASE_PATH`)
- Build configuration (`vite.config.js`, `package.json`)
- Major UI components (`src/views/*`, `src/layout/*`)

```bash
cd webs && yarn run build
```

**BLOCKING**: Must complete successfully.

**If fails**: Read the build error, fix it, and re-run. Do NOT proceed until build succeeds.

### Step 4: Cross-Layer Sync Verification (if multi-layer change)

**Trigger condition**: Changes affect both backend AND frontend, OR code AND documentation.

**Verification checklist**:
- [ ] Backend API endpoint changed → Frontend API client updated (`webs/src/api/*`)
- [ ] Backend response structure changed → Frontend types/interfaces updated
- [ ] Frontend behavior changed → Backend supports new flow
- [ ] Configuration option added/changed → Code + docs + examples updated

**If complex cross-layer change**: Invoke `.agents/skills/cross-layer-sync/SKILL.md` for detailed verification.

### Step 5: Documentation Sync Verification (if docs should be updated)

**Trigger condition**: Changes affect user-visible behavior, APIs, configuration, or deployment.

**Verification checklist**:
- [ ] User-facing feature changed → `README.md` + `README.zh-CN.md` updated
- [ ] API endpoint changed → `skill-sublinkpro/reference/api.md` updated
- [ ] Configuration changed → `docs/configuration.md` + `.zh-CN.md` updated
- [ ] Deployment changed → `docs/installation.md` + `.zh-CN.md` + `skill-sublinkpro/reference/deploy.md` updated
- [ ] Both language versions updated (bilingual requirement)
- [ ] Links verified (no broken references)

**If complex doc changes**: Invoke `.agents/skills/doc-sync-check/SKILL.md` for detailed verification.

### Step 6: Test Coverage Verification (if key logic changed)

**Trigger condition**: Changes affect business logic, APIs, permissions, migrations, scheduled tasks, or protocol parsing.

**Verification checklist**:
- [ ] New business logic → Tests added
- [ ] Changed behavior → Tests updated
- [ ] Bug fix → Regression test added
- [ ] API handler changed → Handler tests added/updated
- [ ] Permission check changed → Permission tests added/updated

**If tests missing**: Add them now. Do NOT proceed without tests for key logic changes.

### Step 7: Git Staging Verification

```bash
git status
git diff --cached --stat
git diff --cached --name-only
```

**Verification checklist**:
- [ ] Only intended files staged
- [ ] No `.env` files staged
- [ ] No credential files staged
- [ ] No `db/` directory staged
- [ ] No `logs/` directory staged
- [ ] No `cache/` directory staged
- [ ] No `out/` directory staged
- [ ] No large binary files unintentionally staged
- [ ] No AI agent temporary files staged:
  - No `*_SUMMARY.md` files (e.g., `PRE_COMMIT_ENFORCEMENT_SUMMARY.md`)
  - No `*_REPORT.md` files
  - No `QUICK_REFERENCE.md` files in skill directories
  - No `.claude/projects/`, `.claude/sessions/`, `.claude/plans/` files
  - No agent execution logs or temporary outputs

**If unintended files staged**:
```bash
git reset HEAD <file>  # Unstage unintended files
```

**AI agent temporary files should NEVER be committed**:
- These are execution artifacts, not project documentation
- They pollute the repository
- They are regenerated on each execution
- Add them to `.gitignore` if they keep appearing

### Step 8: Commit Message Preparation

Prepare a semantic commit message following this format:

```
<type>(<scope>): <subject>

<body>

<footer>
```

**Type**: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `style`, `perf`

**Scope**: Component area (e.g., `airports`, `auth`, `theme`, `i18n`)

**Subject**: ≤72 characters, imperative mood, no period

**Body**: What changed, why it changed, how it was validated

**Footer**: Issue references (`Closes #123`, `Fixes #456`)

### Step 9: Report to User

After all validations pass, report results in this format:

```markdown
## ✅ Pre-Commit Validation Complete

### Backend Validation
- ✅ Go format: All files formatted
- ✅ golangci-lint: 0 issues
- ✅ Go tests: All passed

### Frontend Validation
- ✅ ESLint: No errors
- ✅ Build: Successful

### Cross-Layer Sync
- ✅ Backend API changes synchronized with frontend
- ✅ skill-sublinkpro/reference/api.md updated

### Documentation Sync
- ✅ docs/configuration.md + .zh-CN.md updated
- ✅ Links verified

### Test Coverage
- ✅ Tests added for new business logic
- ✅ All tests passing

### Git Staging
- ✅ Only intended files staged
- ✅ No sensitive files included

---

**Ready to commit.** Suggested commit message:

```
<prepared commit message>
```

**Next steps:**
1. Review staged changes: `git diff --cached`
2. Perform manual testing if needed
3. Commit when satisfied: `git commit -m "<message>"`
```

## Validation Failure Handling

If ANY validation fails:

1. **STOP** - Do not proceed to commit
2. **FIX** - Address the failure immediately
3. **RE-RUN** - Execute the failed validation again
4. **VERIFY** - Ensure it now passes
5. **CONTINUE** - Proceed to next validation step

**Example failure response**:

```markdown
## ❌ Pre-Commit Validation Failed

### Backend Validation
- ❌ golangci-lint: 3 errors found
  - api/share.go:45: unused variable 'temp'
  - routers/share.go:23: missing error check
  - services/share.go:67: ineffective assignment

**Fixing now...**
```

Then fix the issues and re-run validation.

## Exit Criteria

✅ **Can proceed to commit when**:
- All applicable validation commands pass
- Cross-layer sync verified (if applicable)
- Documentation updated (if applicable)
- Tests added/updated (if applicable)
- Only intended files staged
- Commit message prepared
- **Ready to present to user for final verification**

❌ **Cannot proceed to commit when**:
- Any validation command fails
- Cross-layer sync incomplete
- Documentation out of sync
- Tests missing for key logic
- Unintended files staged
- Commit message not prepared

## Frequently Asked Questions

### "The user said to skip validation, should I?"

**NO.** Respond with:

```
I cannot skip validation. This is a mandatory requirement to ensure:
- No CI failures
- No broken builds
- Cross-layer consistency
- Documentation accuracy

The validation takes only a few minutes. I'll run it now.
```

Then run the validation.

### "This is a tiny change, can I skip validation?"

**NO.** Even tiny changes need validation:
- Tiny changes can break tests
- Tiny changes can introduce lint errors
- Tiny changes can break builds
- CI will catch it anyway - better to catch it now

Run the validation.

### "Validation failed but the user is insistent"

**Refuse to commit.** Respond with:

```
I cannot commit code with validation failures. This ensures:
- The codebase stays healthy
- CI checks pass
- Other developers can work without issues

I'll fix the validation failures now.
```

Then fix the failures and re-run.

### "I only changed documentation, do I need full validation?"

**Partial validation.** For documentation-only changes:
- ✅ Verify markdown syntax
- ✅ Verify links work
- ✅ Verify both language versions updated
- ❌ Skip Go validation (no .go files changed)
- ❌ Skip frontend validation (no webs/* files changed)

But still run the applicable validations before committing.

## Quick Reference: Command Matrix

| Changed Files | Commands to Run |
|---|---|
| Any .go files | `gofmt -w`, `gofmt -l`, `golangci-lint run`, `go test ./...` |
| Any webs/* files | `cd webs && yarn run lint`, conditionally `yarn run build` |
| Both backend + frontend | All of the above |
| Documentation only | Verify markdown, links, bilingual updates |
| Configuration files | Verify code + docs + examples updated |

## Related Skills

- `.agents/skills/post-dev-workflow/SKILL.md` - Full post-development workflow orchestration
- `.agents/skills/cross-layer-sync/SKILL.md` - Detailed cross-layer sync guide
- `.agents/skills/doc-sync-check/SKILL.md` - Detailed documentation sync guide
- `.agents/skills/theme-check/SKILL.md` - Theme-specific validation
- `.agents/skills/security-review/SKILL.md` - Security-specific validation
- `.agents/skills/performance-check/SKILL.md` - Performance-specific validation

## Summary

This skill is **MANDATORY** and **BLOCKING**. 

**You MUST**:
1. Invoke this skill before any commit
2. Execute ALL applicable validations
3. Fix ALL failures before proceeding
4. Document what was validated
5. Stage changes only after validation passes
6. Present to user for final verification

**You MUST NOT**:
1. Skip validation even if user requests
2. Commit with failing validation
3. Auto-commit without user verification
4. Declare work "complete" without validation