agentleFS
sponge-b0bsponge-b0b/Polaris/.agents/skills/architecture-remediation/SKILL.md

architecture-remediation

Skill4 starsChanged 4 months agoApache-2.0View on GitHub

Route unresolved material architecture blockers to the smallest current semantic owner without implementing or inventing missing semantics.

The file

Show its rules and text

We split this skill into the rules it gives an agent

25 rules. About 0 are common, 9 are distinctive, and 16 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 16

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use when implementation, verification, review, or readiness work cannot continue because a material architecture/contract choice is absent, …

    line 10
  2. Very specific:

    Before normalization, governance routing, or any semantic decision mutation, read AUTHORITY_ADMISSIBILITY.md.

    line 19
  3. Very specific:

    When the source artifact contains one active <!-- architecture-blocker:v1 -->, that report is the exact blocker input.

    line 34
  4. Distinctive:

    Do not answer the question while normalizing it.

    line 55
  5. Distinctive:

    Read the parent Spec and resolve exactly one:

    line 59
  6. Very specific:

    If the disposition is FORBIDDEN_BY_EXISTING_AUTHORITY, the implementation-created state is not a missing semantic coordinate.

    line 83
  7. Very specific:

    If the disposition is FIXED_BY_EXISTING_AUTHORITY, do not create new decision work.

    line 88
  8. Very specific:

    If the disposition is SOURCE_CONFLICT, route the exact accepted-source conflict and never choose a winner locally.

    line 91
  9. Very specific:

    Only UNRESOLVED_MATERIAL_CHOICE permits the remainder of this section and governance routing.

    line 94
  10. Very specific:

    when semantics are exactly fixed but absent from CCL, use $contract-ledger existing-authority.

    line 104
  11. Very specific:

    If current governing/constraint sources disagree materially at one semantic coordinate, route the exact disagreement as CCL SOURCE CONFLICT.

    line 109
  12. Distinctive:

    If a material choice remains unresolved, continue by governance mode.

    line 112
  13. Very specific:

    When the blocker source workflow is $implement-ticket, architecture routing must also prove that it is consistent with the ticket's …

    line 116
  14. Very specific:

    If the prior feasibility artifact was PASS, the route is valid only when the route request identifies genuinely new post-feasibility …

    line 134
  15. Very specific:

    If the exact governing map is closed and authoritative re-entry is required, reopen that same map with a concise reason identifying the …

    line 158
  16. Distinctive:

    Create or reuse only decision work that belongs to the exact blocker coupling group.

    line 162
  17. Very specific:

    Update the active architecture-blocker disposition to routed with the exact decision references, then emit:

    line 165
  18. Very specific:

    After accepted authority is durable, return through $to-specs so the existing open Spec is reconciled against current CCL before …

    line 194
  19. Distinctive:

    If the Independent blocker legitimately expands into Wayfinder-scale planning, the newly created Wayfinder is the current semantic owner …

    line 197
  20. Very specific:

    When the source uses architecture-blocker:v1, maintain exactly one active managed report and update its disposition in place:

    line 203
  21. Very specific:

    After owner-decision persistence, resume $to-specs.

    line 250
  22. Very specific:

    Run $attention before declaring a blocker fully dispositioned.

    line 263
  23. Distinctive:

    treat an implementation-created state as admissible without the authority-admissibility gate.

    line 272
  24. Distinctive:

    create a second contract beside CCL.

    line 274
  25. Distinctive:

    create a Wayfinder for a bounded Independent decision.

    line 276

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Architecture Remediation

Use when implementation, verification, review, or readiness work cannot continue because a material architecture/contract choice is absent, contradictory, or no longer valid.

This skill is a routing and disposition owner, not a second semantic compiler.

It never implements code and never creates material semantics from blocker prose.

Authority-admissibility precedence

Before normalization, governance routing, or any semantic decision mutation, read AUTHORITY_ADMISSIBILITY.md. It is normative for this skill and overrides more general routing language below where necessary.

A blocker state is not automatically a valid product state merely because an implementation or verifier observed it. $architecture-remediation must first prove whether accepted authority permits that state to exist. New Wayfinder/owner-decision work is allowed only after a valid polaris.architecture-authority-disposition/v1 artifact returns UNRESOLVED_MATERIAL_CHOICE with decision_creation_allowed=true.

Session independence

Recover all correctness-critical state from the invocation, repository, CCL, and durable tracker artifacts. Chat/session memory is context only.

When the source artifact contains one active <!-- architecture-blocker:v1 -->, that report is the exact blocker input. If the invocation explicitly requests an architecture/readiness audit instead, the human-supplied audit scope is the input. Do not silently substitute one mode for the other.

1. Normalize the blocker set

For each blocker capture only:

  • exact unresolved material question or source conflict;
  • current durable evidence;
  • material consequence;
  • affected contract/owner/path/boundary/lifecycle responsibility;
  • exact blocked Spec/ticket/review obligation;
  • governing CCL/ADR/architecture authority already known.

De-duplicate by independent semantic decision, not by symptom count.

Questions are one coupling group when answering one materially constrains the others. They remain separate when each can be resolved independently.

Do not answer the question while normalizing it.

2. Resolve Spec governance

Read the parent Spec and resolve exactly one:

Wayfinder-managed
Independent

Wayfinder-managed means current Spec-local wayfinder-source / wayfinder-remediation provenance establishes one or more governors. Resolve the exact governor whose destination owns this blocker. Ambiguous ownership fails closed.

Independent means no current Wayfinder provenance exists. Do not create a Wayfinder merely because remediation is needed.

Project fields, issue order, branch names, and prior conversation are never governance authority.

3. Test current authority before creating a decision

First apply AUTHORITY_ADMISSIBILITY.md: identify the exact observed state or interval, scan all materially applicable CCL/ADR/platform-architecture/source-workflow authority, build the machine disposition, and validate it with architecture-remediation/scripts/authority_admissibility.py.

If the disposition is FORBIDDEN_BY_EXISTING_AUTHORITY, the implementation-created state is not a missing semantic coordinate. Do not create/reopen/reuse decision work for it. Resolve the architecture blocker with the exact existing authority and return to the source workflow for a compliant realization.

If the disposition is FIXED_BY_EXISTING_AUTHORITY, do not create new decision work. Reconcile a stale Spec projection only when needed; otherwise return directly to the source workflow.

If the disposition is SOURCE_CONFLICT, route the exact accepted-source conflict and never choose a winner locally.

Only UNRESOLVED_MATERIAL_CHOICE permits the remainder of this section and governance routing.

For each admissible unresolved blocker ask:

Does current accepted authority already determine this exact material choice at the required strength?

If yes:

  • identify the exact CCL assertion or governing/constraint authority;
  • when semantics are exactly fixed but absent from CCL, use $contract-ledger existing-authority;
  • mark the blocker resolved only after the authoritative state is durable;
  • return to $to-specs when the Spec projection must change.

If current governing/constraint sources disagree materially at one semantic coordinate, route the exact disagreement as CCL SOURCE CONFLICT. Never choose a winner locally.

If a material choice remains unresolved, continue by governance mode.

Implement-ticket feasibility consistency gate

When the blocker source workflow is $implement-ticket, architecture routing must also prove that it is consistent with the ticket's pre-implementation feasibility verdict.

Recover the exact polaris.implement-feasibility/v1 artifact and exact polaris.architecture-route-request/v1 artifact persisted with the blocker, then run:

python .agents/skills/architecture-remediation/scripts/architecture_route_guard.py \
  --feasibility <implement-feasibility.json> \
  --request <architecture-route-request.json>

Require exactly:

ARCHITECTURE ROUTE: VALID

If the prior feasibility artifact was PASS, the route is valid only when the route request identifies genuinely new post-feasibility evidence. Evidence already enumerated before PASS cannot be reused to start architecture decision work; that means the earlier feasibility verdict was wrong and must be corrected by $implement-ticket to BLOCKED: contract-authority-gap instead.

A failed preferred mechanism, unavailable vendor feature, difficult persistence technique, or other implementation-realization problem is not itself a semantic-authority gap. The route request must name the exact unresolved material authority_coordinate and the governing sources checked. When accepted authority fixes the observable guarantee and leaves physical encoding, private algorithms, query organization, or equivalent realization to implementation, do not route to Wayfinder/owner-decision merely because one realization was rejected.

An $implement-ticket architecture blocker that lacks a valid feasibility artifact, route request, and ARCHITECTURE ROUTE: VALID receipt is not valid input for new semantic decision work under current policy. Do not reopen/create Wayfinder decisions or owner decisions. Leave the blocker unresolved and return it to the source ticket for feasibility correction.

4. Wayfinder-managed blocker

For a Wayfinder-managed Spec, the governing Wayfinder remains the semantic owner only after the authority-admissibility gate permits decision creation.

If the exact governing map is closed and authoritative re-entry is required, reopen that same map with a concise reason identifying the blocked Spec/work, read back the open state, and invoke $project-delivery-management reconcile.

Create or reuse only decision work that belongs to the exact blocker coupling group. Do not create a replacement map or duplicate one decision under several maps.

Update the active architecture-blocker disposition to routed with the exact decision references, then emit:

$wayfinder - <Decision Title> (<Decision URL>)

Wayfinder owns recommendation analysis, human acceptance, and CCL persistence.

5. Independent blocker

For an Independent Spec, use the smallest permanent semantic boundary only after the authority-admissibility gate permits decision creation where decision work is required:

semantics already fixed exactly
    -> $contract-ledger existing-authority

one bounded independent coupling group
    -> $contract-ledger owner-decision

multiple/coupled groups, cross-domain planning, research/prototype campaign,
or project partition/dependency planning
    -> $wayfinder

$architecture-remediation itself does not conduct a parallel owner-decision protocol, maintain a second semantic decision map, or persist a competing architecture contract.

After accepted authority is durable, return through $to-specs so the existing open Spec is reconciled against current CCL before ticketing/implementation resumes.

If the Independent blocker legitimately expands into Wayfinder-scale planning, the newly created Wayfinder is the current semantic owner from that point forward. Do not keep a parallel Independent semantic state machine.

6. Architecture blocker report lifecycle

When the source uses architecture-blocker:v1, maintain exactly one active managed report and update its disposition in place:

unresolved
routed
resolved
  • unresolved — material choice/conflict still blocks progress;
  • routed — exact owning decision artifact is durable;
  • resolved — accepted authority now determines the blocker, including when it forbids the implementation-created state, and any required Spec projection reconciliation has been identified.

Status is routing provenance only; it is not semantic authority.

7. Return paths

Observed state forbidden by existing authority:

$implement-ticket - <Ticket Title> (<Ticket URL>)

This return preserves the verifier/blocker evidence and requires a compliant implementation realization. It does not reopen feasibility, create new semantics, or authorize another architecture decision for the forbidden state.

Resolved by existing/accepted authority and Spec projection may be stale:

$to-specs - <Spec Title> (<Spec URL>)

Wayfinder-owned decision:

$wayfinder - <Decision Title> (<Decision URL>)

Independent bounded owner-decision:

$contract-ledger owner-decision - <Durable Source Title> (<Source URL>)

After owner-decision persistence, resume $to-specs.

Invalid $implement-ticket architecture routing under the feasibility consistency gate:

$implement-ticket - <Ticket Title> (<Ticket URL>)

This return is for feasibility correction only. It does not authorize candidate mutation and must not be used to bypass a valid contract-authority-gap route.

Attention

Run $attention before declaring a blocker fully dispositioned. Attention may expose an additional material question but cannot answer it or enlarge current authority.

Non-goals

$architecture-remediation does not:

  • implement product code;
  • infer material semantics from implementation shape;
  • treat an implementation-created state as admissible without the authority-admissibility gate;
  • design semantics for a state current authority already forbids;
  • create a second contract beside CCL;
  • choose among conflicting governing sources;
  • create a Wayfinder for a bounded Independent decision;
  • turn implementation-mechanism difficulty into a semantic decision;
  • accept a post-PASS architecture route based only on evidence available before feasibility;
  • rewrite completed historical Specs/tickets/ADRs;
  • repair Project projection as though it were lifecycle authority.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.