Feedback

Feedback (reverse cascade)

Overview

Capture a finding from any downstream stage into a structured .forge/feedback/<timestamp>-<source>.md entry that targets one upstream artifact. The entry stays as status: PENDING until the upstream skill re-runs and addresses it. forge-sync flags the target artifact as FEEDBACK_PENDING until the entry is resolved.

This is the only sanctioned reverse-cascade primitive. The forward chain (prd → arch → tasks → code) flows one direction; backward propagation happens through these entries, not by directly editing upstream artifacts mid-stream.

When to Use

• During /build you discover the relevant contract is missing an operation or has the wrong shape
• During /review you find an architectural flaw that wasn't visible at design time
• During /secure or /scale you produce a recommendation that implies architecture changes (add a WAF, change a data store, add a gateway)
• During an incident you discover an error path the error-handling spec didn't cover
• After a sprint, you realize ≥3 tasks split mid-flight — the plan needs an update before the next sprint

When NOT to Use

• The fix is fully contained inside the current stage (don't escalate every implementation detail)
• You have permission to edit the upstream artifact directly and want to do so — then just edit it; forge-sync will flag downstream as STALE
• The finding is a question, not a recommended change — discuss with the user first; file the entry once a recommendation crystallizes
• The target artifact doesn't exist (.forge/security.md not yet generated) — run the source skill instead

Common Rationalizations

Thought	Reality
"I'll just edit the contract inline"	Then the chain has no record of WHY it changed. Future readers see a contract that contradicts the PRD with no explanation.
"Filing a feedback entry is overhead — I'll fix it later"	"Later" means the finding is forgotten by the time the upstream skill re-runs. The entry is the memory.
"The upstream skill will figure it out when it re-runs"	The upstream skill regenerates from its inputs, not from the downstream's discovery. Without a feedback entry, the regenerated artifact has the same flaw.
"This is too small for a feedback entry"	Three small findings ignored = one big surprise at /ship.
"I'll just tell the user verbally"	Verbal findings evaporate. The entry survives session boundaries.

Red Flags

• Editing .forge/contracts/<X>.md directly during /build instead of filing a feedback entry
• A sprint ends with no .forge/feedback/ entries despite ≥3 tasks having notes populated
• forge-sync reports FEEDBACK_PENDING on artifacts that are about to be re-generated, but the regenerating skill doesn't read .forge/feedback/
• A .forge/feedback/*.md file exists with status: PENDING for more than two sprints — either resolve it or mark it DEFERRED with a reason

Core Process

Step 1: Identify source, target, and finding

• Source stage: which skill or activity discovered the issue (build, review, secure, scale, incident, manual)
• Source context: task ID, commit, PR, incident ID, or "manual" if ad-hoc
• Target artifact: which .forge/ file needs revision. Must exist on disk. If multiple files need revision, file separate entries.
• Finding: what was discovered (1-3 sentences, specific)
• Recommended change: what should change in the target artifact (specific enough that re-running the source skill can apply it)

Step 2: Decide severity

Choose one:

• NEEDS_REVIEW — finding requires a human decision; auto-cascade not safe (e.g., "add WAF" — the human decides whether to absorb the change in architecture or defer)
• FEEDBACK_PENDING — recommended change is mechanical; the upstream skill can apply it on re-run (e.g., "add refund endpoint to PaymentService contract")

Both states block /ship. Only NEEDS_REVIEW blocks /build if it touches the in-flight task's contract.

Step 3: Write the entry

Path: .forge/feedback/<ISO8601-UTC-with-dashes>-<source>.md — e.g., .forge/feedback/2026-05-14T103000Z-build.md.

<!-- forge:meta
generated_by: feedback
generated_at: 2026-05-14T10:30:00Z
depends_on: [.forge/contracts/payment-service.md]
generated_from:
  .forge/contracts/payment-service.md: <target's content_hash AT filing time>
content_hash: <first 8 chars of sha256 over this entry's body>
-->

# Feedback: <short title>

- **Source stage:** build (incremental-implementation, task T-042)
- **Source context:** commit pending; branch task/T-042-refund-flow
- **Target artifact:** .forge/contracts/payment-service.md
- **Severity:** FEEDBACK_PENDING
- **Status:** PENDING
- **Filed at:** 2026-05-14T10:30:00Z
- **Resolved at:** —

## Finding

While implementing the refund flow, the PaymentService contract has no `refund(transactionId, amount)` operation. The PRD's "User can refund failed transactions within 30 days" story can't be satisfied without it.

## Recommended change

Add to `Provides` in `.forge/contracts/payment-service.md`:

  refund(input: RefundInput): RefundOutput | RefundError

with:
- `RefundInput = { transactionId: string, amount?: number, idempotencyKey: string }`
- `RefundOutput = { refundId, refundedAt, amount }`
- `RefundError` cases: `TransactionNotFound`, `RefundWindowExpired`, `AlreadyRefunded`, `PartialRefundNotAllowed`

Idempotency-Key required per `api-design.md` mutation policy.

## Cascade

- Re-run `/architect` (or edit the contract directly) to address this entry.
- After contract update, re-run `/plan` if the refund story needs new tasks beyond T-042.
- `forge-sync` will mark this entry `RESOLVED` once the target artifact's `generated_at` advances past this entry's `generated_at` AND the recommended operation appears in the target.

depends_on is the target_artifact (single-element list) — that's what forge-sync reads to identify what's being annotated.

Step 4: Confirm with user

Print the entry path and a one-line summary:

Filed .forge/feedback/2026-05-14T103000Z-build.md — target .forge/contracts/payment-service.md, severity FEEDBACK_PENDING. Run /sync to see chain impact.

Do not modify the target artifact in this skill. The skill is write-only into .forge/feedback/.

Step 5: Tracking resolution

The feedback skill itself does not resolve entries. Resolution happens when the targeted upstream skill re-runs:

1. The upstream skill (e.g., architecture-and-contracts) reads all .forge/feedback/*.md entries where target_artifact matches an output it owns AND status: PENDING.
2. It addresses each in its regeneration.
3. After writing, it updates each addressed entry: status: RESOLVED, resolved_at: <now UTC>, resolved_by: <commit or "manual">.
4. forge-sync confirms the resolution by checking that the target artifact's content reflects the recommended change.

Entries can also be marked DEFERRED (with a reason in the body) when the team decides not to act — the entry stays in the directory as historical record.

Verification

• .forge/feedback/<timestamp>-<source>.md written
• Filename timestamp is UTC with Z; format YYYY-MM-DDTHHMMSSZ-<source>.md
• forge:meta header has depends_on: [<single target artifact path>]
• Severity is one of FEEDBACK_PENDING or NEEDS_REVIEW
• Status is PENDING at filing time
• Recommended change is specific (operation name, type names, error cases — not "make it better")
• Cascade section names which upstream skill should re-run
• No upstream artifact was directly edited by this skill