V0.3.4/troubleshooting

[gimlichael]

This pull request strengthens the guidance and validation around handling hidden or dot-prefixed files (like .bot/, .github/) during .NET skill scaffold installation and generation. It ensures that missing files are treated as local install issues, not template defects, and must be manually restored from the upstream repository before proceeding. The changes also align documentation and validation scripts to enforce this rule consistently across the repository.

Hidden asset recovery and validation:

• Updated CHANGELOG.md, AGENTS.md, and README.md to clarify that missing required or dot-prefixed files during a npx skills add install should be treated as incomplete copies, requiring explicit verification and manual restoration from the upstream repository. [1] [2] [3] [4]
• Added and clarified instructions in skills/dotnet-new-app-slnx/SKILL.md, skills/dotnet-new-lib-slnx/SKILL.md, skills/dotnet-new-app-slnx/references/app.md, and skills/dotnet-new-lib-slnx/references/library.md to require verification and manual restoration of any missing hidden assets before continuing with generation. Checklist items reinforce this requirement. [1] [2] [3] [4] [5] [6] [7]

Validator synchronization:

• Enhanced scripts/validate-skill-templates.ps1 to assert that the updated hidden-asset recovery guidance appears in both app and library scaffold references, ensuring the validator enforces the documented install-fallback behavior.

These updates help prevent confusion between local install issues and template bugs, and ensure all required assets are present before skill generation proceeds.

[greptile-apps]

Greptile Summary

This PR hardens hidden-asset recovery guidance across the .NET scaffold skills (dotnet-new-app-slnx and dotnet-new-lib-slnx) and aligns AGENTS.md, README.md, and the PowerShell validator with the same upstream-verification rule. Changes are documentation and guidance only, with the sole executable change being two new Assert-Contains checks added to scripts/validate-skill-templates.ps1.

Confidence Score: 5/5

Safe to merge; all findings are P2 style suggestions with no runtime or logic impact.

The only executable change is two new string-match assertions in the validator, both of which are verified to match the updated reference files. Remaining findings are a trailing comma typo and inconsistent phrasing between the two validator needles — neither blocks correctness.

scripts/validate-skill-templates.ps1 — the two new Assert-Contains needles use divergent phrasings; worth standardising to reduce future fragility.

Important Files Changed

Filename	Overview
CHANGELOG.md	Updated 0.3.4 release notes to reflect hidden-asset recovery guidance; first "Changed" bullet has a trailing comma typo.
scripts/validate-skill-templates.ps1	Adds two new Assert-Contains checks for hidden-asset recovery wording; the two needles are phrased differently from each other, coupling the validator to divergent reference strings.
AGENTS.md	Minor whitespace-only cleanup and one clarifying sentence added to the per-skill full-test requirement; no logic changes.
README.md	Adds one-sentence install-fallback guidance after the npx skills add command block; correctly documents the hidden-asset recovery rule.
skills/dotnet-new-app-slnx/SKILL.md	Adds hidden-asset recovery paragraph and two checklist items; items cover slightly different scopes (dot-prefixed vs. required files) which appears intentional.
skills/dotnet-new-app-slnx/references/app.md	Inserts the hidden-asset incomplete-copy paragraph; wording matches the validator needle exactly.
skills/dotnet-new-lib-slnx/SKILL.md	Adds hidden-asset recovery paragraph (also covers .docfx/) and one checklist item; consistent with app variant.
skills/dotnet-new-lib-slnx/references/library.md	Inserts the hidden-asset incomplete-copy paragraph; wording matches the lib validator needle but differs from the app variant phrasing.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[npx skills add installs skill] --> B{All files present?}
    B -- Yes --> C[Proceed with scaffold generation]
    B -- No: dot-prefixed / required files missing --> D[Treat as incomplete copy]
    D --> E[Verify upstream repository contents]
    E --> F[Manually restore missing files from source tree]
    F --> G{Validator check: Assert-Contains in validate-skill-templates.ps1}
    G -- app.md needle matches --> H[App scaffold guidance verified]
    G -- library.md needle matches --> I[Lib scaffold guidance verified]
    H & I --> C

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: CHANGELOG.md
Line: 11

Comment:
**Trailing comma on bullet**

The first "Changed" bullet ends with a comma instead of a period, leaving it syntactically incomplete.

```suggestion
- Clarified `dotnet-new-app-slnx` and `dotnet-new-lib-slnx` so missing required or dot-prefixed files in an installed skill copy are treated as a local install mismatch first, with explicit upstream verification and manual restoration before continuing.
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: scripts/validate-skill-templates.ps1
Line: 588-589

Comment:
**Inconsistent needle wording between app and lib assertions**

The two new assertions use materially different phrases for functionally identical guidance:
- app needle: `'manually restore the missing files directly from the repository source tree'`
- lib needle: `'restore the missing files manually from the upstream repository contents'`

This means the validator and the two reference files are permanently coupled to divergent phrasings. If either reference is later edited for clarity it can silently break only one assertion while leaving the other green, making failures harder to diagnose. Standardizing both references (and needles) on a single canonical phrase would make the contract more robust.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "💬 clarify hidden-asset recovery guidanc..." | Re-trigger Greptile}

[greptile-apps]

Trailing comma on bullet

The first "Changed" bullet ends with a comma instead of a period, leaving it syntactically incomplete.

Suggested change

	This is a patch release that hardens the .NET scaffold guidance around hidden asset recovery, making incomplete `npx skills add` installs easier to diagnose and repair before generation continues. The validator and repo docs now reinforce the same upstream-verification and manual-restore rule so local cache or packaging mismatches do not get mistaken for template defects.
	- Clarified `dotnet-new-app-slnx` and `dotnet-new-lib-slnx` so missing required or dot-prefixed files in an installed skill copy are treated as a local install mismatch first, with explicit upstream verification and manual restoration before continuing.

Prompt To Fix With AI

This is a comment left during a code review.
Path: CHANGELOG.md
Line: 11

Comment:
**Trailing comma on bullet**

The first "Changed" bullet ends with a comma instead of a period, leaving it syntactically incomplete.

```suggestion
- Clarified `dotnet-new-app-slnx` and `dotnet-new-lib-slnx` so missing required or dot-prefixed files in an installed skill copy are treated as a local install mismatch first, with explicit upstream verification and manual restoration before continuing.
```

How can I resolve this? If you propose a fix, please make it concise.