Skip to content

Present the skill decomposition position outside the architecture documentation #91

Description

@dieterbaier

Goal

Present the position recorded in ADR-008-skill-decomposition-boundary outside
the architecture documentation, where the people who ask the question actually
are.

Why

Role-based agent architectures — a planner, a coder, a reviewer, each a separate
agent — are common, and teams building one reach the same question this toolkit
already answers: on which axis is the process knowledge cut, and where does the
role-to-skill binding live. ADR-008 answers it, but an ADR inside this
repository's own arc42 is not where that audience looks.

The answer is also not adversarial, which is the part worth carrying outward. A
platform that decomposes its agents by role does not thereby cut its skills
by role. Such a platform sits inside ADR-008's accepted option: the toolkit is
the layer underneath it, not a competitor to it.

What to present

The ADR already contains the material; this is a presentation task, not a new
decision. The pieces that carry outward:

  • The three questions usually asked as one — cut, allocation, agent
    decomposition — and which of them the toolkit decides.
  • The honest comparison, including where a persona cut genuinely wins:
    organisational mappability, and independence of verification.
  • The orchestration illustration from the ADR's Decision, which allocates an
    entry skill per role rather than a list of skills, so the allocation is
    closed under delegation by construction. ADR-008 deliberately does not
    maintain this as an example; if it is shown outside the ADR, this issue is
    where it gets a home.
  • R-007-gate-results-lack-independence as the cost the position accepts, so
    the presentation does not read as a sales pitch.

Venue is the open decision

Candidates, to be chosen when this is picked up rather than now:

Pick one. The ADR stays the single source; whatever is written points back to it
rather than restating the argument, so the two cannot drift.

Acceptance criteria

  • The position is readable by someone who has never opened this repository's
    arc42.
  • The three axes and the toolkit's answer are stated without requiring the
    full ADR.
  • The rejected options keep the strengths ADR-008 credits them with.
  • The accepted cost (R-007) is named, not omitted.
  • The material references ADR-008 as the source instead of restating the
    decision.
  • No new decision is introduced; anything that turns out to be one goes back
    into an ADR first.

Origin

Proposed by the owner while accepting ADR-008 in #88: the illustration does not
need to be maintained inside the repository, but it would be worth reusing if
the decision is presented outside the architecture documentation.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationpriority:p5Strategic, valuable, not urgent

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions