Repository navigation
refactor(skills): within-skill dedup, planning-arch split, cross-skill link CI gate (T2) - #1457
RaduAna-Maria wants to merge 1 commit into
Conversation
…d cross-skill link CI gate Dedup (one home per fact, pointers elsewhere): - maestro-flow: resource-discovery ladder 5→1 (planning-arch §Capability Discovery), validate-once 6→1 (CAPABILITY rule #8), Edit-anchoring mechanics greenfield→editing-operations, agent-vs-script table → agent/planning.md - agents: module-level-LLM rule 4→1 (quickstart Critical Rules), evaluator JSON 2→1 (evaluate.md), auth rules trimmed to authentication.md + two hard one-liners in Critical Rules - coded-apps: npm registry explanation 3→1 (debug.md) - review: stale drifted report-format copy in review-workflow-guide.md replaced with pointer to new canonical template (three-way drift removed) Structure: - maestro-flow planning-arch.md 6,227→4,345 words: plan-document machinery (gate, .arch.plan.md format, mermaid rules) → new plan-document-guide.md, loaded only when producing a plan artifact; Maestro-vs-queue gate reconciled with the orchestration worked example - review SKILL.md 6,591→5,106 words (−23%): report contract → new references/review-report-template.md; Step 2.5 deduped against rule-catalog-workflow.md; anti-patterns compressed in place - maestro-flow SKILL.md frontmatter: brand-first description (was 'TRIGGER for...', forbidden by skill-structure.md), trigger phrasing moved to when_to_use New content: - maestro-flow agent/impl.md: published-agent input-wiring example (was documented only in uipath-agents); agent resource-node inputs take bare references — added the missing uipath.core.agent.* row to node-output-wiring.md's per-node-type table so the single source of truth actually covers agent nodes CI gate: - scripts/check-cross-skill-links.py + validate-cross-skill-links.yml: every cross-skill relative link must resolve and its (source, target) edge must be in the frozen allowlist — new edges fail CI, shrinking the list is encouraged. Caught 3 more broken links on arrival (agents embedding-in-flows/flow-integration → wrong maestro-flow plugin path), fixed here Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Claude finished @RaduAna-Maria's task in 3m 37s —— View job Review: refactor(skills) — within-skill dedup, planning-arch split, cross-skill link CI gate (T2)
SummaryTranche 2 of the efficiency initiative. Three main changes: (1) within-skill deduplication — facts that were restated 3-6x across files are collapsed to one canonical location with pointers; (2) structural splits — Change-by-Change Review1.
|
| Area | Status | Notes |
|---|---|---|
| Frontmatter | OK | maestro-flow rewritten brand-first per skill-structure.md; description within limits |
| E2E Tests | N/A | No new skills added; existing skill changes don't alter CLI workflows |
| Skill Body | OK | All dedup preserves information; pointers are precise with section anchors |
| References & Assets | OK | Two new reference files (plan-document-guide.md, review-report-template.md) are clean extractions; one new input-wiring example fills a real gap |
| Repo Hygiene | OK | No secrets, no unrelated changes, 3 broken cross-skill links fixed, new CI gate prevents regressions |
Issues for Manual Review
- Agent input wiring correctness: The new
node-output-wiring.mdrow andimpl.mdexample assert thatuipath.core.agent.*input slots take bare$varsreferences and reject=js:. This matches the PR description's claim and is consistent with theuipath-agentsembedding-in-flows contract — but the reviewer cannot verify this against the actual UiPath runtime. Domain expert confirmation that=js:truly fails on agent inputs would be valuable. - Maestro gate scoping: The "Is Maestro the Right Home?" gate now explicitly notes that an approval gate inside a multi-wait/mixed-resource flow is normal Maestro design. This is a subtle correctness change to avoid agents incorrectly abandoning Maestro for the very scenario the worked examples present as canonical. Domain review of the scoping is recommended.
Conclusion
Clean, well-structured deduplication PR. Every fact remains stated exactly once, pointers are precise (section-anchored), and the three correctness fixes (broken cross-skill links, agent input wiring, Maestro gate scoping) are well-motivated. The new CI ratchet is a strong addition — it formalizes the "no cross-skill references" rule with a shrink-only allowlist. The net diff (+646/−617) is essentially moves and pointers, not growth.
No blocking issues found. This PR is ready for domain-expert approval on the two manual-review items above.
Summary
Tranche 2 of the efficiency work, stacked on #1456. Within-skill deduplication (one home per fact), structural splits of the two most bloated reading paths, and a CI ratchet that prevents cross-skill link regressions.
Metrics
plan-document-guide.md, loaded only when a plan artifact is producedNet diff: 646 insertions / 617 deletions across 26 files — moves and pointers, not growth.
Correctness fixes folded in
node-output-wiring.md(self-declared single source of truth for=js:rules) had no row foruipath.core.agent.*nodes. Added the row: agent input slots take bare$varsreferences, never=js:(matchesuipath-agentsembedding-in-flows contract and the passingcoded_in_flowe2e tasks). Rule-of-thumb sentence updated with the exception.TRIGGER for..., explicitly forbidden byskill-structure.md); trigger phrasing moved towhen_to_use. Passes the description hook (608 chars; combined ≈818 of 1536).New CI gate
scripts/check-cross-skill-links.py+validate-cross-skill-links.yml:ALLOWED_EDGESratchet — new edges fail CI, shrinking the list is encouraged. Current edge set documented in-script with justifications; the agents↔maestro-flow cycle is marked for consolidation (tranche 4).It caught 3 broken links the manual audit missed on its first run (wrong
references/plugins/path in agents' embedding-in-flows.md / flow-integration.md) — fixed here.Validation
python3 scripts/check-cross-skill-links.py— OKhooks/validate-skill-descriptions.sh skills/*/SKILL.md— all passscripts/check-skill-status.py— OK, 22 skills🤖 Generated with Claude Code