Restructure SA Handbook: Separate Processes, Practices, Playbooks, and Tools

Summary

The Solutions Architects handbook section (/content/handbook/solutions-architects/) conflates processes and practices, making it difficult for SAs to distinguish what is mandatory from what is developmental. This issue tracks a content-neutral restructuring: no new content is to be created, no existing content is to be deleted. The work is to move, rename, and re-index existing pages into a clearer four-section taxonomy, flag redundant content, document all URL changes, and surface URL-breakage risks.

Taxonomy Decision Rule

Before moving any page, apply this test:

Question	Destination
Is an SA required to do this, with defined steps and system touchpoints?	SA Processes
Is an SA encouraged to develop this skill, with judgment and discretion?	SA Practices
Is this an end-to-end guide for a specific selling or engagement motion?	SA Playbooks (new section, no new content — only relocated pages)
Is this a link or reference to a tool, platform, or resource?	SA Tools and Resources

Current File Inventory

`sa-practices/` (currently mixes practices and process-heavy content)

File / Directory	Current path	Correct destination	Notes
`_index.md`	`sa-practices/_index.md`	Update in place	Rewrite index to reflect new scope
`deliberate-practice.md`	`sa-practices/deliberate-practice.md`	SA Practices — Individual skill development	Keep
`effective-objection-handling-practice.md`	`sa-practices/effective-objection-handling-practice.md`	SA Practices — Individual skill development	Keep
`recognizing-cognitive-bias.md`	`sa-practices/recognizing-cognitive-bias.md`	SA Practices — Individual skill development	Keep
`monthly-release-quiz.md`	`sa-practices/monthly-release-quiz.md`	SA Practices — Individual skill development	Keep
`ride-alongs.md`	`sa-practices/ride-alongs.md`	SA Practices — Peer learning	Keep
`sa-office-hours.md`	`sa-practices/sa-office-hours.md`	SA Practices — Peer learning	Keep
`sa-retrospective-feedback.md`	`sa-practices/sa-retrospective-feedback.md`	SA Practices — Team learning	Keep
`communities-of-practice/`	`sa-practices/communities-of-practice/`	SA Practices — Peer learning	Keep directory; includes `integration-technologies.md`
`subject-matter-experts/`	`sa-practices/subject-matter-experts/`	SA Practices — Team learning	Keep directory; includes `sme-cadences.md`, `sme-collateral.md`, `sme-customer-feedback.md`, `sme-engage-pm.md`, `sme-operations.md`, `sme-program.md`, `sme-request.md`
`value-stream-discovery/`	`sa-practices/value-stream-discovery/index.md`	SA Practices — Customer-facing facilitation	Keep
`whiteboard-based-facilitation/`	`sa-practices/whiteboard-based-facilitation/_index.md`	SA Practices — Customer-facing facilitation	Keep
`day-in-the-life.md`	`sa-practices/day-in-the-life.md`	SA Practices — Customer-facing facilitation	Keep
`workshops.md`	`sa-practices/workshops.md`	SA Practices — Customer-facing facilitation	⚠️ Possible overlap with `tools-and-resources/workshop.md` — flag as redundant candidate (see below)
`customer-success-plan/`	`sa-practices/customer-success-plan/_index.md`	SA Processes — Closing and transition	Move to `processes/customer-success-plan/`; has explicit process steps, SFDC hygiene, and manager review cadences
`strategic-solution-selling/`	`sa-practices/strategic-solution-selling/index.md`	SA Playbooks	Move to `playbooks/strategic-solution-selling/`; end-to-end selling motion guide
`business-value-consulting.md`	`sa-practices/business-value-consulting.md`	SA Playbooks	Move to `playbooks/business-value-consulting.md`
`selling-professional-services.md`	`sa-practices/selling-professional-services.md`	SA Playbooks	Move to `playbooks/selling-professional-services.md`; end-to-end guide for a specific engagement motion
`gitlab-dedicated-prospects.md`	`sa-practices/gitlab-dedicated-prospects.md`	SA Playbooks	Move to `playbooks/gitlab-dedicated-prospects.md`; end-to-end guide for a specific prospect motion

`processes/` (mostly correct; some items need sub-grouping)

File / Directory	Current path	Proposed sales-stage grouping	Notes
`_index.md`	`processes/_index.md`	Update in place	Rewrite index to use sales-stage sections
`commercial.md`	`processes/commercial.md`	Pre-qualification — engagement models	Keep
`ecosystem.md`	`processes/ecosystem.md`	Pre-qualification — engagement models	Keep
`ecosystem-sa/esa-operating-rhythm.md`	`processes/ecosystem-sa/esa-operating-rhythm.md`	Pre-qualification — engagement models	Keep
`channel.md`	`processes/channel.md`	Pre-qualification — engagement models	Keep
`alliance.md`	`processes/alliance.md`	Pre-qualification — engagement models	Keep
`collaboration-project.md`	`processes/collaboration-project.md`	Pre-qualification — working agreements	Keep
`technical-discovery.md`	`processes/technical-discovery.md`	Discovery and scoping	Keep
`activity-capture/`	`processes/activity-capture/`	Discovery and scoping — activity capture	Keep directory; includes `activity-logging.md`, `customer-success-plans.md`, `email-logging.md`, `sfdc-logging.md`
`technical-win.md`	`processes/technical-win.md`	Technical evaluation	Keep; likely covers Technical Close Plan trigger criteria
`account-planning.md`	`processes/account-planning.md`	Ongoing	Keep
`sa-opportunity-hygiene.md`	`processes/sa-opportunity-hygiene.md`	Ongoing	Keep
`customer-success-plan/` (moved from sa-practices)	—	Closing and transition	See above
`rfp.md` (moved from tools-and-resources)	—	Closing and transition	Has prescriptive steps for responding to RFPs; belongs in Processes

`tools-and-resources/` (needs conversion to pure reference index)

File / Directory	Current path	Action	Notes
`_index.md`	`tools-and-resources/_index.md`	Update in place	Rewrite as grouped reference index; remove any embedded process steps or practice frameworks
`pov/`	`tools-and-resources/pov/`	Move to SA Playbooks	`_index.md` + `ai.md`, `automation.md`, `compliance.md`, `devsecops.md`, `platform.md` — POV has a highly structured process; the sub-pages are POV-type guides. Move entire directory to `playbooks/pov/`
`rfp.md`	`tools-and-resources/rfp.md`	Move to SA Processes — Closing and transition	Has prescriptive RFP response steps; not a pure reference entry
`trial-guidelines.md`	`tools-and-resources/trial-guidelines.md`	Keep as reference entry	Review for embedded process steps; if prescriptive, move to Processes
`workshop.md`	`tools-and-resources/workshop.md`	Keep as reference entry	⚠️ Possible overlap with `sa-practices/workshops.md` — flag as redundant candidate (see below)
`dap-issue-reporting.md`	`tools-and-resources/dap-issue-reporting.md`	Keep as reference entry	Operational tool reference; keep
`stackoverflow/`	`tools-and-resources/stackoverflow/`	Keep as reference entry	Tool reference; keep

Other top-level files (review for placement)

File	Notes
`demonstrations.md`	Likely belongs in SA Tools and Resources as a demo tooling reference, or in SA Practices if it describes a facilitation skill. Review content before moving.
`sales-plays.md`	Likely belongs in SA Playbooks. Review content before moving.
`sa-career-development.md`	Belongs in SA Enablement or as a standalone page; not Processes or Practices. No move required unless SA Enablement is in scope.
`sa-content.md`	Out of scope for this restructure unless explicitly included.
`sa-documentation.md`	Out of scope for this restructure unless explicitly included.
`sa-leader-shadow.md`	Belongs in SA Practices — Team learning (SA shadows).
`strategic-field-org.md`	Out of scope for this restructure unless explicitly included.
`rules-of-engagement/_index.md`	Review: if it defines trigger conditions and DRIs, move to SA Processes — Pre-qualification.
`sa-enablement/_index.md` + `sa-onboarding.md`	Out of scope for this restructure unless explicitly included.
`center-of-excellence/`	Out of scope for this restructure unless explicitly included.
`sa-manager/`	Out of scope for this restructure unless explicitly included.

New Section to Create: SA Playbooks

Create a new directory content/handbook/solutions-architects/playbooks/ with an _index.md landing page. No new content is written. The index page describes the section purpose and links to the relocated pages below.

Pages to relocate into playbooks/:

Page	Source path	Destination path
POV (main + sub-pages)	`tools-and-resources/pov/`	`playbooks/pov/`
Strategic Solution Selling	`sa-practices/strategic-solution-selling/`	`playbooks/strategic-solution-selling/`
Business Value Consulting	`sa-practices/business-value-consulting.md`	`playbooks/business-value-consulting.md`
Selling Professional Services	`sa-practices/selling-professional-services.md`	`playbooks/selling-professional-services.md`
GitLab Dedicated Prospects	`sa-practices/gitlab-dedicated-prospects.md`	`playbooks/gitlab-dedicated-prospects.md`
Sales Plays	`sales-plays.md`	`playbooks/sales-plays.md` (review first)

Redundant / Repetitive Content — Flag for Review

Do not delete. Add a front-matter note or inline comment flagging the overlap so a future content pass can consolidate.

Pair	Overlap concern
`sa-practices/workshops.md` and `tools-and-resources/workshop.md`	Likely describe the same workshop facilitation topic from two angles. Flag both with a note pointing to the other.
`processes/activity-capture/customer-success-plans.md` and `sa-practices/customer-success-plan/_index.md`	Two pages covering Customer Success Plans in different sections. The `activity-capture` version likely covers SFDC logging; the `sa-practices` version covers the broader process. Flag both.
`processes/technical-win.md` and any Technical Close Plan content embedded in `sa-practices/`	Verify whether Technical Close Plan content is duplicated across files. Flag if so.

URL Change Log

All moves must be tracked here. For each moved file, add a Hugo aliases front-matter entry pointing from the old URL to the new URL so existing links and bookmarks do not break.

Confirmed moves and required aliases

Old URL	New URL	Alias required
`/handbook/solutions-architects/sa-practices/customer-success-plan/`	`/handbook/solutions-architects/processes/customer-success-plan/`	Yes — add `aliases: ["/handbook/solutions-architects/sa-practices/customer-success-plan/"]` to new `_index.md`
`/handbook/solutions-architects/sa-practices/strategic-solution-selling/`	`/handbook/solutions-architects/playbooks/strategic-solution-selling/`	Yes — add alias to new `index.md`
`/handbook/solutions-architects/sa-practices/business-value-consulting/`	`/handbook/solutions-architects/playbooks/business-value-consulting/`	Yes — add alias to new file
`/handbook/solutions-architects/sa-practices/selling-professional-services/`	`/handbook/solutions-architects/playbooks/selling-professional-services/`	Yes — add alias to new file
`/handbook/solutions-architects/sa-practices/gitlab-dedicated-prospects/`	`/handbook/solutions-architects/playbooks/gitlab-dedicated-prospects/`	Yes — add alias to new file
`/handbook/solutions-architects/tools-and-resources/pov/`	`/handbook/solutions-architects/playbooks/pov/`	Yes — add alias to new `_index.md`
`/handbook/solutions-architects/tools-and-resources/pov/ai/`	`/handbook/solutions-architects/playbooks/pov/ai/`	Yes
`/handbook/solutions-architects/tools-and-resources/pov/automation/`	`/handbook/solutions-architects/playbooks/pov/automation/`	Yes
`/handbook/solutions-architects/tools-and-resources/pov/compliance/`	`/handbook/solutions-architects/playbooks/pov/compliance/`	Yes
`/handbook/solutions-architects/tools-and-resources/pov/devsecops/`	`/handbook/solutions-architects/playbooks/pov/devsecops/`	Yes
`/handbook/solutions-architects/tools-and-resources/pov/platform/`	`/handbook/solutions-architects/playbooks/pov/platform/`	Yes
`/handbook/solutions-architects/tools-and-resources/rfp/`	`/handbook/solutions-architects/processes/rfp/`	Yes — add alias to moved file
`/handbook/solutions-architects/sa-practices/sa-leader-shadow/` (if moved from root)	`/handbook/solutions-architects/sa-practices/sa-leader-shadow/`	Verify current URL first

Possible additional URL risks

Any external site, Slack bookmark, Salesforce link, or onboarding doc that deep-links into tools-and-resources/pov/ will break without the alias. Search the handbook for internal links to pov/ before merging.
Any links to tools-and-resources/rfp/ must be updated or aliased — check onboarding docs and the RFx support section of the Tools index.
The sa-practices/ index page likely links to all child pages. Update the index after each move.
The top-level solutions-architects/_index.md navigation links must be updated to add the new Playbooks section and reflect any renamed sections.
Check sa-enablement/sa-onboarding.md for links to any pages being moved — onboarding docs are a common source of stale links.

Step-by-Step Instructions for the Assignee

Phase 1 — Audit (no file changes)

Read each file listed in the inventory above.
For each file in sa-practices/, apply the taxonomy decision rule and confirm the proposed destination in a comment on this issue.
For each file in tools-and-resources/, confirm whether it contains embedded process steps or practice frameworks that need to be stripped before it becomes a pure reference entry.
Search the entire handbook for internal links to tools-and-resources/pov/, tools-and-resources/rfp/, and sa-practices/customer-success-plan/ and list them in a comment.
Flag any additional redundant pairs not listed above.

Phase 2 — Create the Playbooks section

Create content/handbook/solutions-architects/playbooks/_index.md with a brief description of the section purpose (what a playbook is, how it differs from a process or practice). Do not write new substantive content.
Move the files listed in the "New Section to Create" table above into playbooks/.
Add Hugo aliases front-matter to every moved file as listed in the URL Change Log.
Update the sa-practices/_index.md to remove links to moved pages.
Update the tools-and-resources/_index.md to remove the POV section link.

Phase 3 — Reorganize SA Processes index

Edit processes/_index.md to group existing child pages under the five sales-stage headings:
- Pre-qualification
- Discovery and scoping
- Technical evaluation
- Closing and transition
- Ongoing
Move customer-success-plan/ from sa-practices/ to processes/ and add alias.
Move rfp.md from tools-and-resources/ to processes/ and add alias.
Do not rewrite the content of any process page — only update the index groupings and front matter.

Phase 4 — Reorganize SA Practices index

Edit sa-practices/_index.md to group remaining child pages under the four development-domain headings:
- Individual skill development
- Peer learning
- Customer-facing facilitation
- Team learning
Move sa-leader-shadow.md from the root into sa-practices/ if it is not already there, and add an alias.
Do not rewrite the content of any practice page.

Phase 5 — Convert Tools and Resources to a reference index

Edit tools-and-resources/_index.md to restructure as a grouped reference index with these categories:
- Demo and presentation tools
- Customer engagement and recording
- Data seeding and demo environments
- Learning platforms
- SFDC and Rattle hygiene
Remove any embedded process steps or practice frameworks from the index page itself. If substantive process content exists in the index, move it to the appropriate Processes page before removing it.
Review trial-guidelines.md, workshop.md, and dap-issue-reporting.md for embedded process steps and trim or relocate as needed.

Phase 6 — Flag redundant content

For each redundant pair listed above, add the following comment to the top of each file's front matter (do not delete content):
```
# REVIEW: Possible overlap with [other file path]. See restructuring issue for details.
```
Do not merge or delete any content at this stage.

Edit solutions-architects/_index.md to add the Playbooks section to the navigation and update any section descriptions.
Verify all internal cross-links across the four sections resolve correctly.
Run a local Hugo build to confirm no broken internal links or missing aliases.

Phase 8 — Document all changes

Update this issue with a final change log listing every file moved, every alias added, and every redundant pair flagged.
Note any content that was identified as needing a future consolidation pass (but was not changed in this restructure).

Constraints

No new substantive content. Index pages may be rewritten for navigation and section descriptions only.
No content deletions. Flag redundant content with a comment; do not remove it.
Every moved file must have a Hugo alias pointing from its old URL to its new URL.
No URL may go dark without a redirect or alias in place before the MR is merged.
The processes/, sa-practices/, and tools-and-resources/ directories and their existing URLs must remain valid via aliases even after reorganization.

Definition of Done

Edited Apr 21, 2026 by Vladimir Dzalbo (GitLab)