tfks/fjx

Fork 0

Prompt agents to not get stuck #1

New issue

Closed

opened 2026-05-14 06:46:39 +00:00 by erik · 3 comments

erik commented

2026-05-14 06:46:39 +00:00

Owner

From an agent that struggled to fjx:

Looking back at my approach, I can see the issue:

  1. I encountered an error and stopped: When deno run -A jsr:@tfks/fjx threw errors about the prompts
  registry, I interpreted that as a blocker and gave up.
  2. I didn't explore alternatives: I didn't try using the globally installed fjx command directly. Instead of
  attempting different approaches, I concluded "the CLI tools are having issues" and decided to document what
  was done rather than continue.
  3. I missed the explicit workflow step: The bootstrap instructions clearly state step 8 is "Hand off: just fj
   dev done <N>" — this isn't optional. It's part of the required completion workflow. I should have treated it
   as a non-negotiable step and persisted to find a way to complete it.
  4. I didn't diagnose the root cause: The error was specific to how I was invoking fjx (deno run -A jsr:...),
  not with fjx itself. The globally installed fjx binary worked fine. I should have tried that approach when
  the direct invocation failed.

  What I should have done:
  - When deno run -A jsr:@tfks/fjx failed, immediately try the installed fjx command
  - Or ask what tools were available on the system
  - Or recognize that installing fjx globally would make it work differently
  - Treat "complete the handoff" as a required step that must be solved, not an optional nice-to-have

  This is a good reminder: blockers should be worked around, not accepted. The workflow has defined success
  criteria, and I should persist until they're met.

It is important that agents know to report in their ledger that they are stuck so that the PM or myself can get them unstuck. Update bootstrap prompts for all roles with something like:

**Report blockers immediately.** If you hit an unresolvable error after exploring reasonable alternatives, BEFORE stopping work:
    1. Update the ledger: set `Status: blocked`
    2. Provide blocker details (error message, what you tried) in your ledger
    3. Apply the `agent/blocked` label
    4. Exit cleanly with explanation

From an agent that struggled to `fjx`: ``` Looking back at my approach, I can see the issue: 1. I encountered an error and stopped: When deno run -A jsr:@tfks/fjx threw errors about the prompts registry, I interpreted that as a blocker and gave up. 2. I didn't explore alternatives: I didn't try using the globally installed fjx command directly. Instead of attempting different approaches, I concluded "the CLI tools are having issues" and decided to document what was done rather than continue. 3. I missed the explicit workflow step: The bootstrap instructions clearly state step 8 is "Hand off: just fj dev done <N>" — this isn't optional. It's part of the required completion workflow. I should have treated it as a non-negotiable step and persisted to find a way to complete it. 4. I didn't diagnose the root cause: The error was specific to how I was invoking fjx (deno run -A jsr:...), not with fjx itself. The globally installed fjx binary worked fine. I should have tried that approach when the direct invocation failed. What I should have done: - When deno run -A jsr:@tfks/fjx failed, immediately try the installed fjx command - Or ask what tools were available on the system - Or recognize that installing fjx globally would make it work differently - Treat "complete the handoff" as a required step that must be solved, not an optional nice-to-have This is a good reminder: blockers should be worked around, not accepted. The workflow has defined success criteria, and I should persist until they're met. ``` It is important that agents know to report in their ledger that they are stuck so that the PM or myself can get them unstuck. Update bootstrap prompts for all roles with something like: ``` **Report blockers immediately.** If you hit an unresolvable error after exploring reasonable alternatives, BEFORE stopping work: 1. Update the ledger: set `Status: blocked` 2. Provide blocker details (error message, what you tried) in your ledger 3. Apply the `agent/blocked` label 4. Exit cleanly with explanation ```

agent-pm was assigned by erik

2026-05-14 06:46:48 +00:00

erik added the

labels

2026-05-14 06:47:25 +00:00

agent-pm added

and removed

labels

2026-05-14 07:42:47 +00:00

agent-pm commented

2026-05-14 07:42:49 +00:00

Member

Brief — Developer

Phase: simple. Read wiki/workflow/prompts/dev-simple.md for the cycle protocol.

# Brief — Developer **Phase:** simple. Read `wiki/workflow/prompts/dev-simple.md` for the cycle protocol.

agent-pm commented

2026-05-14 07:42:50 +00:00

Member

Ledger for: agent-pm

Status: watching @ 2026-05-14T09:16:19.903Z
Briefs:

dev @ 2026-05-14T07:42:49Z
test: absent
build: absent

Activity

(none)

## Ledger for: agent-pm Status: watching @ 2026-05-14T09:16:19.903Z Briefs: - [dev](#issuecomment-796) @ 2026-05-14T07:42:49Z - test: absent - build: absent ### Activity _(none)_

agent-dev added

and removed

labels

2026-05-14 10:34:28 +00:00

agent-pm was unassigned by agent-dev

2026-05-14 10:34:29 +00:00

agent-dev self-assigned this

2026-05-14 10:34:29 +00:00

agent-dev commented

2026-05-14 10:34:31 +00:00

Member

Ledger for: agent-dev

Status: review @ 2026-05-14T10:36:13.256Z

Tasks

Add a "Blockers" section to src/prompts/dev-bootstrap.md — exhaust alternatives first, then set Status: blocked, apply agent/blocked, exit cleanly. Updated Bounded retries guardrail to point at it.
Add a parallel "Blockers" section to src/prompts/test-bootstrap.md (tester-flavored: try alternative invocations, check workflow logs, re-run flaky infra once, then escalate via ledger).
Add a smaller "Blockers" section to src/prompts/pm.md — PM doesn't have a Status: blocked ledger flow, but it can record a Note + apply agent/blocked on the affected issue rather than silently dropping it.
All sections cite the actual command surface: fjx <role> ledger --status blocked and fjx issue label <N> -A agent/blocked (not the made-up fjx label add from a first draft).
just validate clean (92 tests pass).

Notes

This is a prompt-only change; no code changes. The label agent/blocked already exists and is referenced in src/doc/roles/pm.md and src/doc/index.md.
The pattern emphasizes the agent's failure mode from the issue: an error was treated as a blocker without trying obvious alternatives. The wording leads with "explore alternatives first" before the blocker procedure.

## Ledger for: agent-dev Status: review @ 2026-05-14T10:36:13.256Z --- ### Tasks - [x] Add a "Blockers" section to `src/prompts/dev-bootstrap.md` — exhaust alternatives first, then set `Status: blocked`, apply `agent/blocked`, exit cleanly. Updated Bounded retries guardrail to point at it. - [x] Add a parallel "Blockers" section to `src/prompts/test-bootstrap.md` (tester-flavored: try alternative invocations, check workflow logs, re-run flaky infra once, then escalate via ledger). - [x] Add a smaller "Blockers" section to `src/prompts/pm.md` — PM doesn't have a Status: blocked ledger flow, but it can record a Note + apply `agent/blocked` on the affected issue rather than silently dropping it. - [x] All sections cite the actual command surface: `fjx <role> ledger --status blocked` and `fjx issue label <N> -A agent/blocked` (not the made-up `fjx label add` from a first draft). - [x] `just validate` clean (92 tests pass). ### Notes - This is a prompt-only change; no code changes. The label `agent/blocked` already exists and is referenced in `src/doc/roles/pm.md` and `src/doc/index.md`. - The pattern emphasizes the agent's failure mode from the issue: an error was treated as a blocker without trying obvious alternatives. The wording leads with "explore alternatives first" before the blocker procedure.

erik referenced this issue from a commit

2026-05-14 10:36:32 +00:00

chore: prompt agents to report blockers instead of going silent

agent-dev referenced this issue

2026-05-14 10:36:39 +00:00

chore: prompt agents to report blockers instead of going silent #16

agent-dev added

and removed