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.
In this repository51 other files it gives its agents.
- AGENTS.mdAGENTS.md
- attentionSkill
- classify-docSkill
- codebase-designSkill
- codebase-memory-mcpSkill
- codegraphSkill
- coding-standardsSkill
- contract-ledgerSkill
- conventional-commitsSkill
- database-migrationsSkill
- deduplicate-codeSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- format-codeSkill
- github-issue-dependenciesSkill
- graphifySkill
- grillingSkill
- grill-meSkill
- grill-with-docsSkill
- handoffSkill
- implement-ticketSkill
- improve-codebase-architectureSkill
- project-delivery-managementSkill
- project-trackingSkill
- prototypeSkill
- repowiseSkill
- researchSkill
- resolving-merge-conflictsSkill
- review-architectureSkill
- review-specSkill
- setup-matt-pocock-skillsSkill
- spec-contractSkill
- spec-merge-cleanupSkill
- tddSkill
- teachSkill
- to-adr-docSkill
- to-docSkill
- to-specsSkill
- to-ticketsSkill
- triageSkill
- verify-architectureSkill
- verify-codeSkill
- verify-spec-closureSkill
- verify-specSkill
- verify-ticket-closureSkill
- verify-ticket-decompositionSkill
- wayfinderSkill
- wiki-lintSkill
- wiki-syncSkill
- wiki-synthesizeSkill
- writing-great-skillsSkill
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
- Distinctive: line 10
Use when implementation, verification, review, or readiness work cannot continue because a material architecture/contract choice is absent, …
- Very specific: line 19
Before normalization, governance routing, or any semantic decision mutation, read AUTHORITY_ADMISSIBILITY.md.
- Very specific: line 34
When the source artifact contains one active <!-- architecture-blocker:v1 -->, that report is the exact blocker input.
- Distinctive: line 55
Do not answer the question while normalizing it.
- Distinctive: line 59
Read the parent Spec and resolve exactly one:
- Very specific: line 83
If the disposition is FORBIDDEN_BY_EXISTING_AUTHORITY, the implementation-created state is not a missing semantic coordinate.
- Very specific: line 88
If the disposition is FIXED_BY_EXISTING_AUTHORITY, do not create new decision work.
- Very specific: line 91
If the disposition is SOURCE_CONFLICT, route the exact accepted-source conflict and never choose a winner locally.
- Very specific: line 94
Only UNRESOLVED_MATERIAL_CHOICE permits the remainder of this section and governance routing.
- Very specific: line 104
when semantics are exactly fixed but absent from CCL, use $contract-ledger existing-authority.
- Very specific: line 109
If current governing/constraint sources disagree materially at one semantic coordinate, route the exact disagreement as CCL SOURCE CONFLICT.
- Distinctive: line 112
If a material choice remains unresolved, continue by governance mode.
- Very specific: line 116
When the blocker source workflow is $implement-ticket, architecture routing must also prove that it is consistent with the ticket's …
- Very specific: line 134
If the prior feasibility artifact was PASS, the route is valid only when the route request identifies genuinely new post-feasibility …
- Very specific: line 158
If the exact governing map is closed and authoritative re-entry is required, reopen that same map with a concise reason identifying the …
- Distinctive: line 162
Create or reuse only decision work that belongs to the exact blocker coupling group.
- Very specific: line 165
Update the active architecture-blocker disposition to routed with the exact decision references, then emit:
- Very specific: line 194
After accepted authority is durable, return through $to-specs so the existing open Spec is reconciled against current CCL before …
- Distinctive: line 197
If the Independent blocker legitimately expands into Wayfinder-scale planning, the newly created Wayfinder is the current semantic owner …
- Very specific: line 203
When the source uses architecture-blocker:v1, maintain exactly one active managed report and update its disposition in place:
- Very specific: line 250
After owner-decision persistence, resume $to-specs.
- Very specific: line 263
Run $attention before declaring a blocker fully dispositioned.
- Distinctive: line 272
treat an implementation-created state as admissible without the authority-admissibility gate.
- Distinctive: line 274
create a second contract beside CCL.
- Distinctive: line 276
create a Wayfinder for a bounded Independent decision.
≈ “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.
Files
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
IndependentWayfinder-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-specswhen 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: VALIDIf 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
resolvedunresolved— 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.
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
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.

