SKILL

Process Improvement

Use this skill when you need to change how work is done — update a steering rule, modify an AGENTS.md convention, revise the SDLC, or update contributor guides in open-source repos.

When to Use

• You want to add, modify, or remove a process rule (e.g., a new review gate, a changed naming convention)
• You need to update steering files (.ai/steering/)
• You need to update agent instructions (.ai/agents/cascadeguard/*/AGENTS.md)
• You need to update SDLC docs (.ai/projects/cascadeguard/sdlc.md or cascadeguard-docs)
• You need to update repo-level contributor guides (CONTRIBUTING.md, SDLC.md)
• A board member or manager has approved a process change and you need to implement it

Do NOT

• Post new rules or process changes directly in Paperclip issue comments or descriptions
• Modify process by editing Paperclip issue fields
• Skip the PR step — all process changes must be versioned and reviewable

Prerequisites

• A Paperclip issue authorising or requesting the change
• workspace-management skill available (for worktree creation)
• Git push access to the target repo

Scope Map

Identify which file(s) to change based on the type of process change:

Change Type	Target Location	Repo
Agent operating rules	.ai/steering/*.md	workspace-root
Agent-specific instructions	.ai/agents/cascadeguard/{role}/AGENTS.md	workspace-root
Internal SDLC	.ai/projects/cascadeguard/sdlc.md	workspace-root
IC workflow	.ai/steering/ic-sdlc-workflow.md	workspace-root
Manager standards	.ai/steering/managers.md	workspace-root
Public SDLC (canonical)	docs/sdlc.md (or similar)	cascadeguard-docs
Repo contributor guide	CONTRIBUTING.md	each OS repo
Skill definitions	.ai/skills/{name}/SKILL.md	workspace-root

Workflow

1. Confirm authorisation

Verify there is a Paperclip issue (or comment from a manager/board member) that approves or requests the change. Do not make unsolicited process changes.

2. Identify target files

Use the scope map above to determine which files need editing. If the change spans multiple repos, note each one.

3. Create a workspace

Use the workspace-management skill to create an isolated worktree:

task builder:init BUILDER_NAME={issue-identifier} REPOS={repo-list} BRANCH_NAME=feature/{issue-identifier}-{slug}

Include . (root workspace) for steering/agent/skill changes. Include the relevant repo name for OS repo changes (e.g., cascadeguard-docs).

4. Make the change

Edit the target file(s) in the worktree. Keep changes minimal and focused:

• Add or modify only the relevant section
• Preserve existing formatting and structure
• Do not refactor unrelated content in the same change

5. Commit and push

cd /workspace/.builders/{issue-identifier}/root  # or the relevant repo path
git add {changed-files}
git commit -m "Update {target}: {brief description}
 
Refs: {issue-identifier}
 
Co-Authored-By: Paperclip <noreply@paperclip.ing>"
git push -u origin feature/{issue-identifier}-{slug}

6. Open a PR

Create a PR against the target repo’s main branch. Reference the Paperclip issue in the PR description.

gh pr create --title "{brief title}" --body "Implements process change from {issue-identifier}.
 
## Changes
- {bullet summary}
 
## References
- Paperclip issue: {issue-identifier}"

7. Update the Paperclip issue

Post a comment on the Paperclip issue linking the PR, then set the issue to in_review.

Notes

• For cross-repo changes (e.g., updating CONTRIBUTING.md in multiple repos), create one PR per repo but link them all from the same Paperclip issue.
• If the change affects agent instructions, the affected agents will pick up the new instructions on their next heartbeat after merge.
• Internal process files (.ai/) are in workspace-root. Public-facing docs are in the respective OS repos.