From 928e72360546dac9c02d9d61a10af0ca982f1a67 Mon Sep 17 00:00:00 2001 From: Pol Michel Date: Fri, 20 Feb 2026 12:14:40 +0100 Subject: [PATCH 1/7] new Claude command /pre-ci running locally a subset of the commands that will be executed by the CI. --- dev/commands/pre-ci.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 dev/commands/pre-ci.md diff --git a/dev/commands/pre-ci.md b/dev/commands/pre-ci.md new file mode 100644 index 00000000..18bc431f --- /dev/null +++ b/dev/commands/pre-ci.md @@ -0,0 +1,35 @@ +Run a subset of fast CI checks locally. These are lightweight validations that catch common issues before pushing. Execute each step sequentially and stop on the first failure. Report a summary at the end. + +## Steps + +1. **Format** Python code: + ```bash + uv run invoke format + ``` + +2. **Lint** (YAML, Ruff, ty, mypy, markdownlint, vale): + ```bash + uv run invoke lint + ``` + +3. **Python unit tests**: + ```bash + uv run pytest tests/unit/ + ``` + +4. **Docs unit tests** (vitest): + ```bash + cd docs && npx --no-install vitest run + ``` + +5. **Validate generated documentation** (regenerate and check for drift): + ```bash + uv run invoke docs-validate + ``` + +## Instructions + +- Run each step in order using the Bash tool. +- If a step fails, stop immediately and report the failure with the relevant output. +- At the end, print a summary table of all steps with pass/fail status. +- Do NOT commit or push anything. From cf066492ba90912e3d55a52d4dcb3360e6ceed1f Mon Sep 17 00:00:00 2001 From: Pol Michel Date: Mon, 23 Feb 2026 10:23:46 +0100 Subject: [PATCH 2/7] new Claude command /feedback to identify missing project documentation --- dev/commands/feedback.md | 86 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 dev/commands/feedback.md diff --git a/dev/commands/feedback.md b/dev/commands/feedback.md new file mode 100644 index 00000000..aba5e730 --- /dev/null +++ b/dev/commands/feedback.md @@ -0,0 +1,86 @@ +# Session Feedback + +Analyze the current session and identify what documentation or context was missing, incomplete, or incorrect. The goal is to continuously improve the project's knowledge base so future sessions are more efficient. + +## Step 1: Session Analysis + +Reflect on the work done in this session. For each area, identify friction points: + +1. **Exploration overhead**: What parts of the codebase did you have to discover by searching that should have been documented? (e.g., patterns, conventions, module responsibilities) +2. **Wrong assumptions**: Did you make incorrect assumptions due to missing or misleading documentation? +3. **Repeated patterns**: Did you discover recurring patterns or conventions that aren't documented anywhere? +4. **Missing context**: What background knowledge would have helped you start faster? (e.g., architecture decisions, data flow, naming conventions) +5. **Tooling gaps**: Were there commands, scripts, or workflows that you had to figure out? + +## Step 2: Documentation Audit + +For each friction point identified, determine the appropriate fix. Check the existing documentation to avoid duplicating what's already there: + +- `AGENTS.md` — Top-level project instructions and component map +- `CLAUDE.md` — Entry point referencing AGENTS.md +- `docs/AGENTS.md` — Documentation site guide +- `infrahub_sdk/ctl/AGENTS.md` — CLI development guide +- `infrahub_sdk/pytest_plugin/AGENTS.md` — Pytest plugin guide +- `tests/AGENTS.md` — Testing guide + +Read the relevant existing files to understand what's already documented before proposing changes. + +## Step 3: Generate Report + +Present the feedback as a structured report with the following sections. Only include sections that have content — skip empty sections. + +### Format + +```markdown +## Session Feedback Report + +### What I Was Working On + + +### Documentation Gaps + + +For each gap: +- **Topic**: What's missing +- **Where**: Which file should contain this (existing file to update, or new file to create) +- **Why**: How this would have helped during this session +- **Suggested content**: A draft of what should be added (be specific and actionable) + +### Documentation Corrections + + +For each correction: +- **File**: Path to the file +- **Issue**: What's wrong or misleading +- **Fix**: What it should say instead + +### Discovered Patterns + + +For each pattern: +- **Pattern**: Description of the convention +- **Evidence**: Where in the code this pattern is used (file paths) +- **Where to document**: Which AGENTS.md or guide file should capture this + +### Memory Updates + + +For each update: +- **Action**: Add / Update / Remove +- **Content**: What to write +- **Reason**: Why this is worth remembering across sessions +``` + +## Step 4: Apply Changes + +After presenting the report, ask the user which changes they want to apply. Present the options: + +1. **Apply all** — Create/update all proposed documentation files and memory +2. **Cherry-pick** — Let the user select which changes to apply +3. **None** — Just keep the report as reference, don't modify any files + +For approved changes: +- Edit existing files when updating documentation +- Create new files only when no appropriate existing file exists +- Update `MEMORY.md` with approved memory changes +- Keep all changes minimal and focused — don't over-document From 03fe2dce5a060ca562bd3980fd51c0f779643b2f Mon Sep 17 00:00:00 2001 From: Pol Michel Date: Mon, 23 Feb 2026 10:36:45 +0100 Subject: [PATCH 3/7] would be more convenient to have all the results at once after /pre-ci command since they are independent checks --- dev/commands/pre-ci.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dev/commands/pre-ci.md b/dev/commands/pre-ci.md index 18bc431f..efb2de8c 100644 --- a/dev/commands/pre-ci.md +++ b/dev/commands/pre-ci.md @@ -1,4 +1,4 @@ -Run a subset of fast CI checks locally. These are lightweight validations that catch common issues before pushing. Execute each step sequentially and stop on the first failure. Report a summary at the end. +Run a subset of fast CI checks locally. These are lightweight validations that catch common issues before pushing. Run all steps and report a summary at the end. ## Steps @@ -30,6 +30,6 @@ Run a subset of fast CI checks locally. These are lightweight validations that c ## Instructions - Run each step in order using the Bash tool. -- If a step fails, stop immediately and report the failure with the relevant output. +- If a step fails, continue with the remaining steps. - At the end, print a summary table of all steps with pass/fail status. - Do NOT commit or push anything. From bc144dd0269cf664a7ab25c6d426db885b40e73b Mon Sep 17 00:00:00 2001 From: Pol Michel Date: Tue, 24 Feb 2026 20:58:49 +0100 Subject: [PATCH 4/7] encapsulating the 4th command into a subshell to avoid changing the working directory --- dev/commands/pre-ci.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev/commands/pre-ci.md b/dev/commands/pre-ci.md index efb2de8c..91e8fd68 100644 --- a/dev/commands/pre-ci.md +++ b/dev/commands/pre-ci.md @@ -19,7 +19,7 @@ Run a subset of fast CI checks locally. These are lightweight validations that c 4. **Docs unit tests** (vitest): ```bash - cd docs && npx --no-install vitest run + (cd docs && npx --no-install vitest run) ``` 5. **Validate generated documentation** (regenerate and check for drift): From 514d7d31992cb4a4b35cc1de01c48185e1d4fba5 Mon Sep 17 00:00:00 2001 From: Pol Michel Date: Tue, 24 Feb 2026 20:59:34 +0100 Subject: [PATCH 5/7] new blank line to make linters happy --- dev/commands/feedback.md | 1 + 1 file changed, 1 insertion(+) diff --git a/dev/commands/feedback.md b/dev/commands/feedback.md index aba5e730..a870afd6 100644 --- a/dev/commands/feedback.md +++ b/dev/commands/feedback.md @@ -80,6 +80,7 @@ After presenting the report, ask the user which changes they want to apply. Pres 3. **None** — Just keep the report as reference, don't modify any files For approved changes: + - Edit existing files when updating documentation - Create new files only when no appropriate existing file exists - Update `MEMORY.md` with approved memory changes From 8abbde24a8229a6d69aa10a92f53c33eac525688 Mon Sep 17 00:00:00 2001 From: Pol Michel Date: Tue, 24 Feb 2026 21:05:55 +0100 Subject: [PATCH 6/7] replaced ambiguous term "session" with "conversation" into feedback command --- dev/commands/feedback.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/dev/commands/feedback.md b/dev/commands/feedback.md index a870afd6..e4a4dbed 100644 --- a/dev/commands/feedback.md +++ b/dev/commands/feedback.md @@ -1,10 +1,10 @@ # Session Feedback -Analyze the current session and identify what documentation or context was missing, incomplete, or incorrect. The goal is to continuously improve the project's knowledge base so future sessions are more efficient. +Analyze this conversation and identify what documentation or context was missing, incomplete, or incorrect. The goal is to continuously improve the project's knowledge base so future conversations are more efficient. ## Step 1: Session Analysis -Reflect on the work done in this session. For each area, identify friction points: +Reflect on the work done in this conversation. For each area, identify friction points: 1. **Exploration overhead**: What parts of the codebase did you have to discover by searching that should have been documented? (e.g., patterns, conventions, module responsibilities) 2. **Wrong assumptions**: Did you make incorrect assumptions due to missing or misleading documentation? @@ -35,7 +35,7 @@ Present the feedback as a structured report with the following sections. Only in ## Session Feedback Report ### What I Was Working On - + ### Documentation Gaps @@ -43,7 +43,7 @@ Present the feedback as a structured report with the following sections. Only in For each gap: - **Topic**: What's missing - **Where**: Which file should contain this (existing file to update, or new file to create) -- **Why**: How this would have helped during this session +- **Why**: How this would have helped during this conversation - **Suggested content**: A draft of what should be added (be specific and actionable) ### Documentation Corrections From 6387a79193de1048530ed12b1ef19ef41ea9d445 Mon Sep 17 00:00:00 2001 From: Pol Michel Date: Wed, 25 Feb 2026 10:14:06 +0100 Subject: [PATCH 7/7] additional blank lines --- dev/commands/feedback.md | 5 +++++ dev/commands/pre-ci.md | 1 + 2 files changed, 6 insertions(+) diff --git a/dev/commands/feedback.md b/dev/commands/feedback.md index e4a4dbed..b89896be 100644 --- a/dev/commands/feedback.md +++ b/dev/commands/feedback.md @@ -41,6 +41,7 @@ Present the feedback as a structured report with the following sections. Only in For each gap: + - **Topic**: What's missing - **Where**: Which file should contain this (existing file to update, or new file to create) - **Why**: How this would have helped during this conversation @@ -50,6 +51,7 @@ For each gap: For each correction: + - **File**: Path to the file - **Issue**: What's wrong or misleading - **Fix**: What it should say instead @@ -58,6 +60,7 @@ For each correction: For each pattern: + - **Pattern**: Description of the convention - **Evidence**: Where in the code this pattern is used (file paths) - **Where to document**: Which AGENTS.md or guide file should capture this @@ -66,6 +69,7 @@ For each pattern: For each update: + - **Action**: Add / Update / Remove - **Content**: What to write - **Reason**: Why this is worth remembering across sessions @@ -79,6 +83,7 @@ After presenting the report, ask the user which changes they want to apply. Pres 2. **Cherry-pick** — Let the user select which changes to apply 3. **None** — Just keep the report as reference, don't modify any files + For approved changes: - Edit existing files when updating documentation diff --git a/dev/commands/pre-ci.md b/dev/commands/pre-ci.md index 91e8fd68..7f14d70d 100644 --- a/dev/commands/pre-ci.md +++ b/dev/commands/pre-ci.md @@ -33,3 +33,4 @@ Run a subset of fast CI checks locally. These are lightweight validations that c - If a step fails, continue with the remaining steps. - At the end, print a summary table of all steps with pass/fail status. - Do NOT commit or push anything. +