Introducing SDD structure for Services Page

[mariana-caldas]

Web Dev Path

Have you updated the CHANGELOG.md file? If not, please do it.

Yes.

What is this change?

This pull request introduces a lightweight Specification-Driven Development (SDD) structure for the Services Page initiative.

Added:

• /specs/services-page/specification.md
• /specs/services-page/decisions.md
• /specs/services-page/tasks.md
• /specs/services-page/references.md

Together, these documents create a shared source of truth for the initiative by capturing:

• Project goals and requirements
• Technical and product decisions
• Implementation tasks
• Design references
• Environment references
• External integrations

The goal is to reduce ambiguity, improve onboarding, and provide implementation context before development begins.

This approach is increasingly common in AI-assisted development workflows because tools such as Claude, GitHub Copilot, Cursor, and ChatGPT perform significantly better when they receive structured project context instead of isolated implementation requests.

For example, instead of prompting:

Build the Hero section.

contributors can provide specification.md, decisions.md, references.md, and correspondent task while asking the AI assistant to implement the Hero section according to the documented requirements and constraints.

This allows AI tools to understand business goals, design constraints, implementation decisions, and project context before generating code.

Were there any complications while making this change?

No technical complications.

The primary challenge was defining a lightweight structure that provides value without introducing unnecessary process overhead for contributors.

Rather than adopting the complete GitHub Spec Kit workflow, this implementation focuses on four core documents:

• specification.md
• decisions.md
• tasks.md
• references.md

How to test this PR?

Review the newly created files:

• /specs/services-page/specification.md
• /specs/services-page/decisions.md
• /specs/services-page/tasks.md
• /specs/services-page/references.md

Validate that:

• Figma references are correct.
• Netlify staging references are correct.
• Tasks align with the approved Services Page mockups.
• Decisions align with previous team discussions.
• Documentation is clear enough for a new contributor to understand the initiative without additional context.

When should this be merged?

After at least 3 reviews from the team.

Once approved, Project Managers will use the documented tasks as a starting point for creating GitHub Issues.

The tasks file is intended to guide planning and prioritization, while GitHub Issues will remain the primary mechanism for assigning, tracking, and delivering implementation work.

This should be merged before implementation begins on the Services Page so contributors can use the specifications as the primary implementation reference.

[netlify]

✅ Deploy Preview for webdevpathstage ready!

Name	Link
🔨 Latest commit	83c3cf3
🔍 Latest deploy log	https://app.netlify.com/projects/webdevpathstage/deploys/6a2f75b5574308000888ed36
😎 Deploy Preview	https://deploy-preview-306--webdevpathstage.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[cherylli]

Hi, it includes all the changes from last PR, you probably need to rebase your branch with the new changes

[mariana-caldas]

Hi, it includes all the changes from last PR, you probably need to rebase your branch with the new changes

Thanks, @cherylli . The goal is to develop services on a separate branch (services-dev) that has everything main has so far. That's why my current branch feat\add-sdd-structure is bringing the last changes we merged into main from #305
During the development phase, if we pick anything else (a bug, for example) on our platform (main), we need to fix that and bring those changes into services-dev as well. Does it make sense?

[cherylli]

Hi, it includes all the changes from last PR, you probably need to rebase your branch with the new changes

Thanks, @cherylli . The goal is to develop services on a separate branch (services-dev) that has everything main has so far. That's why my current branch feat\add-sdd-structure is bringing the last changes we merged into main from #305
During the development phase, if we pick anything else (a bug, for example) on our platform (main), we need to fix that and bring those changes into services-dev as well. Does it make sense?

Yeah sorry my bad, I thought it was being merged into main. Didn't look properly