docs: update AI agent guidelines (Human label, find-and-open args, PR/issue templates) (#46)

* docs: fix inaccurate ValueError claim for oversized values in set() docstrings

Made-with: Cursor

* docs: update AGENTS.md and cursor skills/commands for Human label and improved PR/issue templates

Made-with: Cursor

* revert: restore Python file changes already committed in another PR

Co-authored-by: Fabien MARTY <fabien-marty@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Fabien MARTY <fabien-marty@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

.cursor/commands/issues/find-and-open.md

@@ -6,26 +6,43 @@ Thoroughly review the ENTIRE codebase to identify bugs, improvements, architectu
 
 **This command is read-only: DO NOT modify any source file, test, config, or documentation.**
 
+## Arguments (`$ARGUMENTS`)
+
+Parse the optional `$ARGUMENTS` string for the following keywords (case-insensitive). Multiple keywords can be combined.
+
+| Keyword  | Effect |
+|----------|--------|
+| `medium` | Do **not** open GitHub issues for `Priority: Low` findings — only display them in the summary output. |
+| `high`   | Do **not** open GitHub issues for `Priority: Medium` or `Priority: Low` findings — only display them in the summary output. |
+| `local`  | Do **not** open any GitHub issue at all — only display all findings in the summary output. |
+| `bug`    | Only open GitHub issues for bug findings (those that would receive the `Type: Fixed` label); all other findings are only displayed in the summary output. |
+
+When multiple keywords are present, apply all matching rules (most restrictive wins for priority filters).
+
 ## Steps
 
 1. **Read `AGENTS.md`** to understand the project conventions and constraints.
 
-2. **Search existing github issues** to know what has already been reported. Avoid creating duplicate tasks.
+2. **Parse `$ARGUMENTS`** and determine which findings will be opened as GitHub issues vs. only displayed (see Arguments table above).
+
+3. **Search existing github issues** to know what has already been reported. Avoid creating duplicate tasks.
 
-3. **Review the entire codebase systematically.** Read all source files, tests, configuration files, and documentation.
+4. **Review the entire codebase systematically.** Read all source files, tests, configuration files, and documentation.
 
-4. **For each issue found**, create a GitHub issue with:
-   - A clear, specific **title**
-   - A **description** explaining the issue, where it is (file + approximate location), why it matters, and a suggestion for fixing it
-   - **Label**: `Reporter: AI` + `Type: ...` + `Priority: ...` (never add a `Status: ...` label when creating an issue)
+5. **For each issue found**, decide based on the parsed arguments whether to:
+   - **Create** a GitHub issue with:
+     - A clear, specific **title**
+     - A **description** explaining the issue, where it is (file + approximate location), why it matters, and a suggestion for fixing it
+     - **Label**: `Reporter: AI` + `Type: ...` + `Priority: ...` (never add a `Status: ...` label when creating an issue)
+   - **Or only display** it in the summary output (no GitHub issue created).
 
-5. **At the end**, display a summary table of all tasks created, grouped by label, showing task ID and title.
+6. **At the end**, display a summary table of all findings grouped by label, showing task ID (or `—` if not created) and title, with a note indicating which were opened vs. display-only.
 
 ## Important rules
 
 - **DO NOT modify any file in the repository.** This command is purely analytical.
 - **DO NOT create duplicate tasks.** Always check the existing GitHub issues before creating a new task.
 - **Be specific.** Each task should address one concrete, actionable issue — not vague observations.
-- **Be honest.** Only report genuine issues, not stylistic nitpicks that conflict with the project's established conventions
+- **Be honest.** Only report genuine issues, not stylistic nitpicks that conflict with the project's established conventions.
 - **Group related micro-issues.** If you find multiple typos in the same file or closely related minor issues, group them into a single task rather than creating many tiny tasks.
 - **It's OK if you don't find any issue!** In that case, just display a message "No issue found".

.cursor/skills/manage-github-issues/SKILL.md

@@ -14,7 +14,7 @@ Use the `gh` command line tool for all GitHub issue operations. When creating is
 | List issues | `gh issue list` |
 | List open issues | `gh issue list --state open` |
 | View issue | `gh issue view <number>` |
-| Create issue | `gh issue create --title "..." --body "..." --label "ai"` |
+| Create issue | `gh issue create --title "..." --body "..." --label "Reporter: AI"` |
 | Edit issue | `gh issue edit <number> --title "..." --body "..."` |
 | Close issue | `gh issue close <number>` |
 
@@ -66,8 +66,9 @@ gh label create "Priority: High"      --color "e4181b" --description "High prior
 gh label create "Priority: Medium"    --color "fbca04" --description "Medium priority"
 gh label create "Priority: Low"       --color "c5def5" --description "Low priority"
 
-# Reporter label
+# Reporter / workflow labels
 gh label create "Reporter: AI"        --color "d4c5f9" --description "Created by AI agent"
+gh label create "Human"               --color "fbca04" --description "Requires human intervention"
 
 # Status labels
 gh label create "Status: Validated"   --color "99d708" --description "Validated and ready to plan/implement"
@@ -136,6 +137,7 @@ gh issue list --limit 20
 We use the following standardized labels:
 
 - `Reporter: AI` - Issues created by AI agents
+- `Human` - Issues that require human intervention (AI agents should skip these)
 
 - `Status: Validated` - Issues that have been validated and that are ready to be planned/implemented
 - `Status: Planning` - Issues that are being worked on in planning mode

.cursor/skills/manage-github-pull-requests/SKILL.md

@@ -25,15 +25,17 @@ Use the `gh` command line tool for all GitHub pull request operations.
 When creating or editing PRs, use this template for the body:
 
 ```markdown
-## Description
+## Summary
 
-[Describe the changes in 1–3 paragraphs. Reference linked issues with Fixes #123 or Closes #123.]
+[1–3 bullet points describing what this PR does and why]
 
-## Checklist
+## Changes
 
-- [ ] Tests pass (`make test`)
-- [ ] Linting passes (`make lint`)
-- [ ] Documentation generated (`make doc`)
+[Brief list of the key files / components changed and why]
+
+## Related issues
+
+Closes #<issue-number>   ← remove if no related issue
 ```
 
 ## Creating PRs
@@ -42,29 +44,35 @@ When creating or editing PRs, use this template for the body:
 
 ```bash
 gh pr create --title "Title here" --body-file - << 'EOF'
-## Description
+## Summary
+
+- Fix cache eviction bug when TTL expires
 
-Description text. Fixes #42.
+## Changes
 
-## Checklist
+- `atomic_lru/cache.py`: corrected eviction logic
+- `tests/test_cache.py`: added regression test
 
-- [ ] Tests pass (`make test`)
-- [ ] Linting passes (`make lint`)
-- [ ] Documentation generated (`make doc`)
+## Related issues
+
+Closes #42
 EOF
 ```
 
 **Inline body**:
 
 ```bash
-gh pr create --title "Title" --body "## Description
+gh pr create --title "Title" --body "## Summary
+
+- Short description of what this PR does
+
+## Changes
 
-Description text.
+- List of key changes
 
-## Checklist
+## Related issues
 
-- [ ] Tests pass (\`make test\`)
-- [ ] Linting passes (\`make lint\`)" --label "Type: Fixed"
+Closes #42" --label "Type: Fixed"
 ```
 
 **Autofill from commits**:

AGENTS.md

@@ -33,6 +33,7 @@ We use the following standardized labels.
 ### For issues only
 
 - `Reporter: AI` - Issues created by AI agents
+- `Human` - Issues that require human intervention (AI agents should skip these)
 
 - `Status: Validated` - Issues that have been validated and that are ready to be planned/implemented
 - `Status: Planning` - Issues that are being worked on in planning mode