Experimental claude skill for puzzletron algoritgm

[danielkorzekwa]

What does this PR do?

Type of change: new feature

Experimental claude skill for puzzletron compression algorithm. See .agents/skills/puzzletron/README.md for details

Usage

see .agents/skills/puzzletron/README.md

Testing

• Please test it manually before approving MR.
• Propose automated way of testing

Before your PR is "Ready for review"

• Is this change backward compatible?: ✅
• Did you write any new necessary tests?: tested manually only
• Did you update Changelog?: ✅
• Did you get Claude approval on this PR?: ✅ / ❌ / N/A

Summary by CodeRabbit

Release Notes

• New Features

  • Introduced an experimental agent skill for Puzzletron with /puzzletron mip and /puzzletron all to run the MIP step or the full pipeline.
  • Added progress reporting via /puzzletron mip progress and /puzzletron all progress, including per-step elapsed time and estimated remaining time.

• Documentation

  • Added comprehensive skill workflow documentation, including command usage and example progress output.
  • Updated Puzzletron example docs with AI agent integration guidance.

• Chores

  • Linked the Claude skill directory to the new skill documentation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 38a5b3d4-9952-4517-9204-8d065f739e60

📥 Commits

Reviewing files that changed from the base of the PR and between afb6a71 and ca9d8b4.

📒 Files selected for processing (3)

• .agents/skills/puzzletron/SKILL.md
• .agents/skills/puzzletron/all_progress.py
• .agents/skills/puzzletron/mip_progress.py

🚧 Files skipped from review as they are similar to previous changes (1)

• .agents/skills/puzzletron/all_progress.py

---

📝 Walkthrough

Walkthrough

Adds an experimental Claude Code agent skill for Puzzletron under .agents/skills/puzzletron/. The skill defines /puzzletron mip and /puzzletron all slash commands via SKILL.md, with two Python progress-reporting scripts (all_progress.py, mip_progress.py) that parse log.txt and print per-step/per-rate elapsed and remaining-time tables. A symlink wires the skill into .claude/skills/, and docs and changelog are updated.

Changes

Puzzletron Agent Skill

Layer / File(s)	Summary
Slash-command routing spec .agents/skills/puzzletron/SKILL.md	Defines front-matter metadata, /puzzletron subcommand routing (all, mip, progress), nproc_per_node parsing and validation, torchrun execution with log tee and "Puzzletron Progress" filtering, and delegation to the progress scripts.
Full-pipeline progress script .agents/skills/puzzletron/all_progress.py	Reads ./log.txt, parses per-step timestamps and descriptions, extracts in-flight signals (solution validation counts, batch progress, MIP solver nodes), estimates remaining time, and prints a formatted 8-step status table with elapsed and remaining time per step.
MIP-step progress script .agents/skills/puzzletron/mip_progress.py	Reads ./log.txt, detects sweep vs. no-sweep mode from compression-rate entries, computes per-rate elapsed times and remaining estimates, prints per-rate [ ]/[RUNNING]/[DONE] progress tables with solver timing details, and extracts the results output path.
Documentation, symlink, and changelog .agents/skills/puzzletron/README.md, .claude/skills/puzzletron, examples/puzzletron/README.md, CHANGELOG.rst	Adds the agent skill user-facing README with command usage and example output tables, a symlink from .claude/skills/puzzletron to the agents directory, a new "Using with AI agents" subsection in the Puzzletron example README, and a changelog entry.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• kevalmorabia97
• kaix-nv
• meenchen
• shengliangxu
• chadvoegele
• claude

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title contains a typo ('algoritgm' instead of 'algorithm') and is broadly related to the changeset but lacks clarity about the specific nature of the skill or its purpose.	Consider revising the title to fix the typo and be more specific about what the skill does, e.g., 'Add experimental Claude skill for Puzzletron compression workflow' or similar.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Security Anti-Patterns	✅ Passed	All Python files comply with SECURITY.md requirements: no unsafe deserialization, no eval/exec, no hardcoded secrets, no shell injection, no nosec comments, only standard library imports, no new de...

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dkorzekwa/puzzletron_claude_skill

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 64.78%. Comparing base (bcd8dd4) to head (afb6a71).
⚠️ Report is 14 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1769      +/-   ##
==========================================
+ Coverage   58.45%   64.78%   +6.32%     
==========================================
  Files         510      511       +1     
  Lines       56271    56792     +521     
==========================================
+ Hits        32896    36791    +3895     
+ Misses      23375    20001    -3374     

Flag	Coverage Δ
examples	41.80% <ø> (+19.36%)	⬆️
unit	54.33% <ø> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Warning

CodeRabbit couldn't request changes on this pull request because it doesn't have sufficient GitHub permissions.

Please grant CodeRabbit Pull requests: Read and write permission and re-run the review.

👉 Steps to fix this

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.agents/skills/puzzletron/all_progress.py:
- Around line 80-84: The variables `cur_b` and `total_b` are only defined inside
the elif block when `batch_matches` is truthy, but they are used later in the
code (around line 100) regardless of which conditional branch executes. When the
if condition on line 80 evaluates to true (sol_done is not None and sol_total is
truthy), the elif block is skipped entirely, leaving `cur_b` and `total_b`
undefined. Extract the batch data unpacking logic (extracting pct, cur_b, and
total_b from batch_matches[-1]) before the if-elif conditional block to ensure
these variables are always defined when batch_matches is non-empty, preventing
NameError when they are referenced later in the code.

In @.agents/skills/puzzletron/mip_progress.py:
- Around line 53-59: Replace the hardcoded source line number markers with
content-based semantic markers to make detection robust to code refactoring. In
the completion detection block around line 57, replace the condition checking
for "sweep.py:292" with a check for "Results written to:" which is the actual
completion message. In the related detection block around lines 109-114 that
currently guards on "sweep.py:258", remove the line number check entirely and
instead use unconditional regex matching on the "compression_rate=" pattern
which is already a proven approach used at line 99 for results detection.

In @.agents/skills/puzzletron/SKILL.md:
- Around line 34-40: The specification lacks numeric validation for the
nproc_per_node parameter before it is interpolated into shell commands, creating
a security vulnerability for shell injection attacks. Add an explicit validation
rule to both the "all" and "local" command sections in the skill specification
that checks whether nproc_per_node matches the pattern of a positive integer
(^[0-9]+$). Insert this validation check after the "value not found" check and
before the "Otherwise use the parsed value" instruction in both sections. If the
value is not strictly numeric, the specification should instruct to ask the user
"nproc_per_node must be a positive integer." and STOP before any shell command
execution occurs.
- Around line 46-53: The shell pipeline using torchrun piped to tee piped to
grep does not properly propagate exit codes because without pipefail, the
pipeline only returns the exit code of the rightmost command (grep). When
torchrun fails but grep successfully finds the "Puzzletron Progress" pattern,
the pipeline reports success even though the actual torchrun command failed. To
fix this, add set -o pipefail before or at the beginning of the script block
containing the torchrun command to ensure that the pipeline returns a non-zero
exit code when any command in the pipeline fails, allowing accurate exit code
reporting as mentioned in the instructions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: f507f804-2357-44dd-934e-633f88d0cd06

📥 Commits

Reviewing files that changed from the base of the PR and between 769ea5f and afb6a71.

📒 Files selected for processing (7)

• .agents/skills/puzzletron/README.md
• .agents/skills/puzzletron/SKILL.md
• .agents/skills/puzzletron/all_progress.py
• .agents/skills/puzzletron/mip_progress.py
• .claude/skills/puzzletron
• CHANGELOG.rst
• examples/puzzletron/README.md