Han Feedback: software-architect-junior-developer-adversarial-validator (2026-08-06)

[mxriverlynn]

Han Feedback — 2026-08-06

Skills used: none (that is the finding — see below; the surrounding session separately ran
han-coding:refactor, han-coding:manual-test-planning, han-coding:tdd, and
han-communication:readability-guidance) Agents used: han-core:software-architect,
han-core:junior-developer, han-core:adversarial-validator Context: The user needed a small API
designed — a change to a shared multi-step flow provider component in a React app, letting URL
query-string values prefill a flow's steps — scoped to a single ticket and sized for a single PR.
Outcome: No Han skill fit the request, so the user hand-orchestrated three Han agents themselves.
The result was good, and the orchestration prompt the user had to write is itself the specification
for a missing skill.

Method note. This file was compiled from an on-disk session transcript. The three agents ran in
that session, dispatched directly by user instruction, not by any skill.

---

The request, verbatim in shape

The user's dispatching turn contained, in one prompt, everything a skill would otherwise encode:

"we need to design a change to the flow provider that allows for injecting values. the specific
design change we come up with will replace what we are currently doing in this branch. […] apply a
single consistent API design […] i need a software architect to design this, with a junior
developer to ask questions about it, and an adversarial validator to poke holes in it. all of
this must be constrained to the goal of [the ticket] for now. every aspect of the API design must
be justified from the [ticket] goal. give me options, first, ignoring everything that was changed
in the current branch and assuming we will start over from origin/main. write all of this to a
folder in .scratch/ as you go"

The user specified: the deliverable (design options with one recommendation), the agent team and
their adversarial arrangement, the scope constraint (every design element justified from one ticket's
goal), the starting state (ignore the current branch), and the artifact location. A skill exists to
carry exactly this kind of procedural knowledge so the user does not have to re-derive it per
request.

What worked well

• The three-agent arrangement produced a design that survived contact. The architect wrote a
  numbered context brief and options document; the junior developer raised 20 numbered questions; the
  architect amended the design in response; the adversarial validator then attacked the amended
  design. The final API (initial values win at mount, never persist, invalid input degrades to a
  normal visit) shipped essentially as designed and later survived a full code review.
• The junior-developer round earned its turns. One of its questions surfaced a naming decision
  the user reversed on the spot ("why is X renamed to Y? … i prefer to keep the name X"), before any
  code existed.
• The "every aspect justified from the ticket goal" constraint worked as a scope governor. It
  kept the architect from designing a general-purpose injection framework when one consumer needed
  one behavior.

What didn't work

• No skill fronted the request, so the user did the orchestration by hand. The catalog has no
  properly sized entry:
  • han-planning:plan-implementation assumes an existing feature specification and a team-scale
    effort. The user's own read: it "implies a higher level perspective and planning for a larger
    project or effort." Correct.
  • han-planning:plan-a-feature interviews for product behaviors. This request was not "what should
    the feature do" — the behavior was known. It was "what is the right contract shape": signatures,
    types, precedence and persistence invariants, failure behavior.
  • han-coding:architectural-analysis assesses existing structure; it does not design new
    interfaces.
  • han-core:software-architect has the right altitude — its charter is intra-codebase interface
    design with pseudocode sketches — but no skill front door. Its own description says it works from
    findings other agents produced, which normally means the full analyst fan-out, oversized here.
• The user also had to hand-build the evidence pipeline the agents consumed. The context brief of
  verified findings (structural facts, runtime behavior, consumer audit, requirements with
  provenance) was assembled ad hoc in the session before the architect was dispatched. A skill would
  own that discovery step.

Proposal: a design-an-api skill (working name; also floated as /api-design)

Sized between refactor and plan-a-feature. The deliverable is a designed contract, not a spec and
not a delivery plan.

• Trigger: the user wants to design an API change, interface, or contract within one codebase —
  a component's props, a function surface, URL parameters, a module boundary — for a capability they
  can already describe, sized for roughly one PR.
• Shape, generalized directly from this session:
  1. A light discovery pass (codebase-explorer or equivalent) producing a context brief of verified
     findings with provenance — replacing the full structural/behavioral/risk fan-out.
  2. software-architect produces an options document with one recommendation and rejected
     alternatives, every element justified from the stated goal.
  3. junior-developer questions the options; the architect amends.
  4. adversarial-validator attacks the amended design.
  5. Artifacts written to the configured output directory as the run goes; open items surfaced one at
     a time for user decision (the user asked for exactly this: "show me the open items, one at a
     time").
• Boundaries to state: designs contracts, does not specify features (plan-a-feature), does not
  plan delivery (plan-implementation), does not write the code (tdd) or restructure existing code
  (refactor). Output feeds directly into a tdd run, which is what happened in this session.

Overall

The agents did the work well; the gap is the missing front door. The user reproduced, by hand and
from memory, a five-step pipeline with a three-agent adversarial arrangement and a scope-discipline
rule — and it worked, which is the strongest evidence the pipeline deserves to be packaged. The
prompt that dispatched it reads like a SKILL.md waiting to be written.

Rating

Ratings apply to the direct agent runs, since no skill fronted the request.

Dimension	Score
Output accuracy	5/5
Evidence discipline	4/5
Finding signal-to-noise	4/5
Output length vs. decision count	4/5
Turn efficiency	3/5

Accuracy 5/5: the designed API shipped essentially as specified and survived a later code review.
Evidence discipline 4/5: the context brief carried provenance for every requirement, but only because
the user demanded "validated and verified evidence" repeatedly in the turns leading up to it.
Signal-to-noise 4/5: the junior developer's 20 questions included several that changed the design and
a tail that did not. Length 4/5: proportionate options document; the amendment round grew it. Turn
efficiency 3/5: docked for the hand-orchestration itself — the turns the user spent specifying the
pipeline, the team, and the artifact locations are precisely the turns a skill exists to remove.