Agent hard process

Agent Hard Process

Overview

Agents often say “lesson learned” and then repeat the same mistake next week.

This skill fixes that failure mode. It turns a hard-won result into a replayable process: exact steps, rejected attempts, source truth, benchmark harness, acceptance gates, and a clean replay before the workflow is trusted.

Use it for any workflow where the final answer is not enough. The agent must preserve how the answer was reached and prove the process still works.

When to use

Use this skill when someone says or implies:

• save this workflow
• make this a hard process
• learn every step
• benchmark it
• future agents must not repeat this mistake
• we had to iterate many times before it worked
• this result needs a 10/10 replay, not a memory note

Also use it after complex work with five or more tool calls when the process produced a reusable lesson, a non-obvious command, a tool gotcha, or a repeatable QA loop.

Do not use it for temporary task progress, raw transcripts, stale PR numbers, one-off notes, or facts that belong in memory instead of a procedure.

Core rule

A workflow is not saved when it is written down.

A workflow is saved only after it is replayed from a clean state and verified with real evidence.

Required output surfaces

1. Skill or workflow document
2. Benchmark script or replay recipe
3. Failure history
4. Acceptance checklist
5. Verification output from real tools
6. Final human-readable report

The eight-step hard process

1. Capture the approved truth

Identify the final result that was accepted. Preserve the exact user correction or approval phrase if it defines success.

Record:

• canonical artifact or source truth
• final commands or settings
• rejected earlier attempts
• acceptance criteria in the user’s language

2. Extract the workflow primitives

Turn the successful method into exact primitives:

• inputs and references
• commands
• code snippets
• prompts
• configuration values
• test or benchmark steps
• expected final artifacts

Replace vague instructions with measurable gates. “Looks right” is not enough. Use decode output, file dimensions, visual match, schema validation, unit tests, screenshot comparison, or another observable signal.

3. Preserve the failure history

Future agents repeat defaults. Keep the rejected attempts visible.

Use this format:

❌ Failed: <attempt> — <why it failed>
✅ Fixed: <working method>

4. Codify the process

Create or patch the smallest durable skill/workflow document that owns this class of work.

Include:

• trigger conditions
• exact steps
• exact commands or code
• acceptance checklist
• pitfalls
• verification commands
• final delivery shape
• update rule for future corrections

5. Build a clean replay harness

Minimum benchmark options:

• Visual/design: side-by-side comparison plus targeted vision or geometry checks
• Code: failing regression first, then passing fix
• Document/PDF: page size, render, OCR/text extraction, file integrity
• Automation/cron: direct script run, no-op vs alert behavior, logs
• Data/API: dry-run sample input, schema checks, source-truth validation
• Skill persistence: reload the skill and confirm final values are present

6. Rank, fix, and rerun

Run multiple benchmark cases when feasible. Rank them lowest to highest score. Fix the weakest blocker first, then rerun the full suite.

Suggested score guide:

• 10/10: all checks pass and final artifact matches source truth
• 8–9/10: usable but missing proof or one non-blocking edge case
• 5–7/10: important gap, patch before trusting
• below 5/10: redesign the process

If any case scores below 10/10, patch the workflow and rerun.

7. Verify the saved workflow itself

Reload or re-read the saved skill/workflow after patching it.

Confirm:

• final tuned values are present
• failure history is preserved
• benchmark recipe is complete
• acceptance gates are explicit
• linked references/templates load

8. Report material changes

Final report should be short and evidence-backed:

• Updated/Implemented: yes/no and what changed
• New capability: what the process can now do
• Why it matters: plain English
• Verified: exact commands/tests/tool outputs
• Files changed
• Next move, if useful

Acceptance checklist

Before a hard process is considered saved:

• Approved source truth is captured
• Exact reproduction steps are documented
• Failure history is documented
• Acceptance gates are measurable
• Clean replay was run
• Benchmark artifacts exist
• Real tool output verifies the result
• Skill/workflow was patched with final tuned values
• Saved workflow was reloaded or re-read
• Final report lists changed files and verification evidence

Benchmark folder pattern

<project>/<workflow-name>-benchmark-YYYYMMDD/
├── benchmark_<workflow>.py|sh
├── benchmark-results.json
├── benchmark-compare.png        # visual workflows only
├── BENCHMARK-REPORT.md
└── regenerated-output/

Common pitfalls

1. Saving before replaying. Written instructions are not proof.
2. Saving only the final answer. Future agents need the path, not just the artifact.
3. Hiding failures. The rejected defaults are the most valuable part.
4. Using vague gates. “Good enough” does not survive handoff.
5. Forgetting to patch the skill after benchmark tuning.
6. Testing only the original example. Add a second sample, negative control, or stress case when safe.
7. Trusting tool defaults. Record exact non-default flags.
8. Reporting without evidence. Include the command output, screenshot, decode log, metric JSON, or rendered artifact.

One-shot recipe

1. Identify the approved final result.
2. Write the exact workflow.
3. Build a benchmark or replay test.
4. Run it from a clean folder.
5. Patch the workflow if the replay finds drift.
6. Rerun until the gates pass.
7. Reload the saved workflow.
8. Report changed files and verification evidence.