Sitecore Feature Optimisation Playbook

Purpose: Step-by-step process for optimising any Sitecore MVC feature component —
from initial evidence capture through refactoring, multi-agent review, deployment,
and TOBE verification.
Applies to: Example — Feature.Header, Feature.Navigation, Feature.Footer and any new Feature.

Overview

ASIS Evidence → Design → Multi-Agent Review → Build → Deploy → TOBE Evidence → Compare → Ship

Each phase is described below with exact agent prompts, tool commands, and acceptance criteria.

Phase 1 — ASIS Evidence Capture

Goal: Photograph the component exactly as it exists today before any change is made.
This is the baseline you compare against at the end.

1.1 Identify the rendering

Use SPE to find the rendering item by controller and action:

Get-ChildItem -Path "master:/sitecore/layout/Renderings" -Recurse |
    Where-Object {
        $_.Fields["Controller"].Value -eq "<Controller>" -and
        $_.Fields["Controller Action"].Value -eq "<Action>"
    } | Select-Object -First 1 | ForEach-Object { "$($_.Name)|$($_.ID)" }

Record the Rendering ID — you will need it throughout.

1.2 Find 5 diverse pages that use the rendering

Query the web database (published items only). Select pages from different top-level
sections of the site to maximise coverage:

$renderingId = "{YOUR-RENDERING-ID}"
Get-ChildItem -Path "web:/sitecore/content/Example/Home" -Recurse |
    Where-Object { $_.Fields["__Final Renderings"].Value -like "*$renderingId*" } |
    Select-Object -First 20 | ForEach-Object {
        $url = [Sitecore.Links.LinkManager]::GetItemUrl($_)
        "$($_.DisplayName)|$url"
    }

1.3 Capture screenshots and HTML

For each of the 5 pages, at two viewports:

Viewport	Size
Desktop	1280 × 800
Mobile	390 × 844

Steps per page per viewport:

Navigate to https://corp1031sc.dev.local{url}
Dismiss the OneTrust cookie banner (#onetrust-accept-btn-handler)
Confirm the component is visible (offsetHeight > 0)
Scroll component into view and apply yellow outline: element.style.outline = '5px solid yellow'
Take a viewport-only screenshot (fullPage: false)
Capture outerHTML and save as .html

File naming: {page-slug}-desktop.png, {page-slug}-mobile.png, {page-slug}.html
Save to: C:\TFS\Team Inbox\Evidence\{ActionName}\

1.4 Write the ASIS evidence document

Save {ActionName}-Evidence.md in the same folder. Include:

Rendering ID and path
Controller / Action (ASIS values)
Component selector used
DOM structure notes
Table linking each page to its screenshot files

Phase 2 — Refactoring Design

Goal: Plan all code changes before writing a single line. The design must address
speed, testability, HELIX compliance, and reuse of existing Foundation patterns.

2.1 Refactoring objectives (apply all)

Objective	Approach
Speed	POCO-cache pattern — resolve Sitecore items once, store plain C# objects in `UNNCache`, serve from cache on subsequent requests
Testability	No `Sitecore.Context` calls in service constructors. All Sitecore dependencies injected via interfaces. Services fully unit-testable with Moq.
Remove Glass dependency	Replace `IGlassBase` models with POCO classes. Services read item fields directly.
HELIX compliance	Feature projects must not reference other Feature projects. Cross-cutting concerns (cache provider base, `IRequestStateResolver`, `CacheKeyBuilder`, shared POCOs) move to Foundation.Common.
Reuse	Check Foundation.Common for existing helpers (`GetImageUrl`, `GetLinkedItems`, `Url()`, `StartItem()`). Do not duplicate. Check other Feature services for the same pattern before writing new code.
DI-friendly	Services registered as `Transient`. Cache providers registered as `Singleton`. All interfaces registered in a `ServicesConfigurator` + Sitecore config patch.

2.2 Standard POCO-cache pattern

Controller
  └─ IXxxService (Transient)
       └─ IXxxCacheProvider (Singleton) : IUNNCacheProvider<CachedXxxData>
            └─ SitecoreUNNCacheProvider<CachedXxxData>  [Foundation.Common]
       └─ CachedXxxData  [Feature.Xxx.Models — pure POCO, no Sitecore types]
       └─ XxxViewModelMapper  [static, Func<ID,bool> delegates for current/active state]
  └─ XxxOptimisedViewModel  [passed to View]

2.3 New files to create (per feature)

File	Location
`CachedXxxData.cs`	`Feature.Xxx\Models\`
`IXxxCacheProvider.cs`	`Feature.Xxx\Services\`
`SitecoreXxxCacheProvider.cs`	`Feature.Xxx\Services\`
`IXxxService.cs`	`Feature.Xxx\Services\`
`XxxService.cs`	`Feature.Xxx\Services\`
`XxxViewModelMapper.cs`	`Feature.Xxx\Services\`
`XxxOptimisedViewModel.cs`	`Feature.Xxx\Models\ViewModels\`
`XxxOptimised.cshtml`	`Feature.Xxx\Views\Xxx\`
`XxxServiceTests.cs`	`Feature.Xxx.MSTests\`
`XxxViewModelMapperTests.cs`	`Feature.Xxx.MSTests\`

2.4 Foundation.Common shared infrastructure

Confirm these already exist before creating them:

Class	Namespace	Purpose
`IUNNCacheProvider<T>`	`Common.Cache`	Generic get/set cache interface
`SitecoreUNNCacheProvider<T>`	`Common.Cache`	Abstract base — wraps `UNNCache`
`CacheKeyBuilder`	`Common.Cache`	Builds `{feature}_{version}_{site}_{itemId}_{lang}` keys
`IRequestStateResolver`	`Common.PageContext`	`IsCurrentPage(ID)` and `IsActive(ID)`
`RequestStateResolver`	`Common.PageContext`	Per-request ancestor-set caching
`CachedSocialLinkBase`	`Common.Models`	Shared base for social link POCOs

If any are missing, create them in Foundation.Common and register via CommonConfigurator.config.

Phase 3 — Multi-Agent Design Review (10 Agents)

Goal: Independent review from 10 distinct angles before writing any code.
Run all 10 agents in parallel in a single message.

Spawn each as a background Agent with run_in_background: true.

#	Agent focus	Key question
1	HELIX compliance	Does any Feature reference another Feature? Are all cross-cutting types in Foundation?
2	Caching strategy	Are cache keys unique per site + language? Will UNNCache auto-clear on publish? Any stampede risk?
3	Testability	Can every service method be tested with Moq and no Sitecore context? Are all Sitecore calls behind interfaces?
4	Performance	Any N+1 Sitecore item reads? Are linked items resolved in a single pass? Is index used where appropriate?
5	DI correctness	Correct lifetimes (Transient/Singleton)? Any captive dependency (Singleton holding Transient)?
6	View safety	Does the new view handle null gracefully? Will it render correctly in EE? Are all fields null-checked?
7	Backwards compatibility	Does the old rendering (Glass/legacy) still work if the swap hasn't been done yet?
8	Data fidelity	Does the POCO capture every field the view consumes? Are computed fields (e.g. `HasImage`, `HasCssClass`) pre-built and stored?
9	Test coverage gaps	Are ctor null-guards tested? Cache-hit/miss paths? Null datasource? Mapper field passthrough?
10	Naming and consistency	Are names consistent with existing patterns (e.g. `CachedXxxData`, `SitecoreXxxCacheProvider`)?

Each agent should return a bullet-point list of findings, rated Pass / Warning / Fail.
Resolve all Fails and Warnings before proceeding to implementation.

Phase 4 — Sitecore Best Practice Review (5 Agents)

Goal: Validate the design against Sitecore documentation and official guidance.
Run all 5 in parallel.

Use mcp__sitecore-documentation-docs__search_sitecore_knowledge_sources for lookups.

#	Agent focus	Search terms
1	Dependency Injection	`Sitecore DI IServicesConfigurator Transient Singleton Scoped`
2	Caching	`Sitecore CustomCache UNNCache cache invalidation publish end`
3	HELIX architecture	`HELIX Foundation Feature Project layer dependencies`
4	Content Search / index	`Sitecore ContentSearch ISearchIndex GetResults navigation index`
5	MVC rendering pipeline	`Sitecore MVC RenderingContext Controller Action GetModel`

Each agent should confirm whether the proposed approach matches official guidance,
and flag any deviations with a suggested correction.

Phase 5 — Implementation

Goal: Write all code changes as designed in Phase 2, incorporating feedback from Phases 3-4.

Rules

All implementation delegated to background sub-agents (run_in_background: true)
Spawn parallel agents for independent work (e.g. service + tests can be written simultaneously)
Never implement on the main thread
Create a project branch before touching any file: git checkout -b {ticket}-{description}
Never commit without explicit user instruction
After every agent completes, verify the diff matches expectations

Implementation order

Foundation.Common — any new shared types first (other features depend on these)
Feature POCOs — CachedXxxData and sub-models
Cache provider pair — IXxxCacheProvider + SitecoreXxxCacheProvider
Service — IXxxService + XxxService
ViewModel mapper — XxxViewModelMapper (static, pure functions)
ViewModel — XxxOptimisedViewModel
View — XxxOptimised.cshtml
ServicesConfigurator + Sitecore config patch
MSTests — service tests + mapper tests + controller tests
csproj updates — add <Compile> entries for all new files

Phase 6 — Build

Run MSBuild against the full solution. Fix all errors before proceeding.

& "C:\Program Files\Microsoft Visual Studio\18\Enterprise\MSBuild\Current\Bin\MSBuild.exe" `
    "C:\TFS\CorpWebsite\src\Unn.Ac.CorporateWebsite.sln" `
    "/p:Configuration=Release" `
    "/p:Platform=Any CPU" `
    /t:Build /m /nologo

Acceptance criteria: Build succeeded. with 0 errors. Pre-existing warnings are acceptable.

Common build errors and fixes

Error	Likely cause	Fix
CS0234 `PageContext`	New `Common.PageContext` namespace shadows `Sitecore.Mvc.Presentation.PageContext`	Fully-qualify as `Sitecore.Mvc.Presentation.PageContext.Current`
CS0012 `IUNNCacheProvider<>` not visible	Test project missing Foundation.Common ProjectReference	Add `<ProjectReference>` to test csproj
C# 7 syntax in project targeting Roslyn 1.x	Pattern matching (`is T x`) in legacy project	Rewrite as `as`-cast + null check
CS1061 `.Count` on `IEnumerable<T>`	Missing `using System.Linq`	Add using, change to `.Count()`

Phase 7 — Deploy to IIS

Copy all changed DLLs and config files to the local IIS site.

$src  = "C:\TFS\Example\src"
$dest = "C:\inetpub\wwwroot\Example.dev.local"

# DLLs (one per changed project)
Copy-Item "$src\Foundation\Example.Common\bin\*.dll" "$dest\bin\" -Force
Copy-Item "$src\Feature\Example.Xxx\bin\*.dll"      "$dest\bin\" -Force

# Config patches
Copy-Item "$src\Foundation\...\App_Config\Include\Z.Custom\Configurators\*.config" `
    "$dest\App_Config\Include\Z.Custom\Configurators\" -Force

# Views (if changed)
Copy-Item "$src\Feature\Example.Xxx\Views\Xxx\XxxOptimised.cshtml" `
    "$dest\Views\Xxx\" -Force

# Always copy CSS when copying any view
Copy-Item "$src\Project\Example.Web\Common\css\style.min.css" `
    "$dest\Common\css\style.min.css" -Force

Phase 8 — Swap the Rendering

Do not commit the rendering swap — it should be done manually at release time.

In Sitecore, find the rendering item and update via SPE:

$item = Get-Item -Path "master:" -ID "{RENDERING-ID}"
$item.Editing.BeginEdit()
$item.Fields["Controller"].Value        = "Xxx"          # was "XxxGlass"
$item.Fields["Controller Action"].Value = "XxxOptimised" # was "Xxx"
$item.Editing.EndEdit()

Then clear all caches:

[Sitecore.Caching.CacheManager]::ClearAllCaches()

Phase 9 — TOBE Evidence Capture

Repeat Phase 1 exactly, using the same 5 pages and the same viewports.

File naming: {page-slug}-tobe-desktop.png, {page-slug}-tobe-mobile.png
Save to: same folder as ASIS — C:\TFS\Team Inbox\Evidence\{ActionName}\

Phase 10 — Compare ASIS vs TOBE

For each of the 5 pages, verify:

Check	Method
Component is visible	`offsetHeight > 0` at both viewports
No layout regression	Visual comparison — same nav items, same structure
No rendering errors	Page title must not contain "Error" or "Runtime Error"
No missing data	Navigation items, links, social icons all present
Performance improvement	(Optional) Compare response time headers

Acceptance criteria: All 5 pages pass all checks at both viewports.

If any page fails

Read the Sitecore log: C:\inetpub\wwwroot\example.dev.local\App_Data\logs\
Check for DI resolution errors — ensure ServicesConfigurator registers all required interfaces
Check for null reference exceptions — add null-guards or fix missing field reads
Fix → rebuild → redeploy (Phase 6-7) → re-capture the failing page only → re-verify

Repeat until all 5 pages pass.

Phase 11 — Commit and Push

Only after all TOBE checks pass:

# Stage specific files (never git add -A)
git add src/Foundation/... src/Feature/Xxx/... Unicorn/...

# Commit with a descriptive message
git commit -m "Add XxxOptimised POCO-cache rendering — Items N-M

- CachedXxxData POCO replaces Glass model
- IXxxCacheProvider / SitecoreXxxCacheProvider (SitecoreUNNCacheProvider<T>)
- CacheKeyBuilder keys include siteName + language
- XxxViewModelMapper — static, pure functions, fully testable
- MSTest coverage: ctor guards, null datasource, cache-hit/miss, mapper passthrough
- XxxOptimised.cshtml view wired to HeaderOptimised action

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"

git push origin {branch-name}

Do not commit the Sitecore rendering swap (the Unicorn YAML) — that goes in a
separate release-time commit when the rendering is officially switched in production.

Checklist Summary

[ ] ASIS evidence captured (5 pages, desktop + mobile + HTML)
[ ] Refactoring design documented
[ ] 10 design-review agents run — all Fails/Warnings resolved
[ ] 5 Sitecore best-practice agents run — all deviations corrected
[ ] Implementation complete — all files created/updated
[ ] Build succeeded (0 errors)
[ ] DLLs + config + views deployed to IIS
[ ] Rendering swapped in Sitecore (master only, not committed)
[ ] Sitecore caches cleared
[ ] TOBE evidence captured (same 5 pages, same viewports)
[ ] ASIS vs TOBE comparison passed — all 5 pages, both viewports
[ ] Commit and push (rendering swap excluded)
[ ] Memory file written to C:\Users\xxx\.claude\projects\C--TFS\memory\

Reference: Key Paths

Resource	Path
Solution	`C:\TFS\CorpWebsite\src\Unn.Ac.example.sln`
MSBuild	`C:\Program Files\Microsoft Visual Studio\18\Enterprise\MSBuild\Current\Bin\MSBuild.exe`
IIS root	`C:\inetpub\wwwroot\example.dev.local\`
Evidence	`C:\TFS\Team Inbox\Evidence\{ActionName}\`
Memory	`C:\Users\svdo1\.claude\projects\C--TFS\memory\`
Foundation.Common	`src\Foundation\Unn.Ac.example.Common\`
Sitecore logs	`C:\inetpub\wwwroot\example.dev.local\App_Data\logs\`
Dev site URL	`https://example.dev.local`